@trishchuk/coolors-mcp 1.0.0

package/src/tools/registry.ts

@@ -0,0 +1,142 @@
+import { Prompt, Tool } from "@modelcontextprotocol/sdk/types.js"; // Each tool definition includes its metadata, schema, prompt, and execution logic in one place.
+import { ZodError, ZodTypeAny } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+export interface UnifiedTool {
+  category?: "codex" | "simple" | "utility";
+  description: string;
+  execute: (
+    args: Record<string, unknown>,
+    onProgress?: (newOutput: string) => void,
+  ) => Promise<string>;
+
+  name: string;
+
+  prompt?: {
+    arguments?: Array<{
+      description: string;
+      name: string;
+      required: boolean;
+    }>;
+    description: string;
+  };
+  zodSchema: ZodTypeAny;
+}
+
+export const toolRegistry: UnifiedTool[] = [];
+
+export async function executeTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  onProgress?: (newOutput: string) => void,
+): Promise<string> {
+  const tool = toolRegistry.find((t) => t.name === toolName);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${toolName}`);
+  }
+  try {
+    const validatedArgs = tool.zodSchema.parse(args);
+    return tool.execute(validatedArgs, onProgress);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const issues = error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join(", ");
+      throw new Error(`Invalid arguments for ${toolName}: ${issues}`);
+    }
+    throw error;
+  }
+}
+
+export function getPromptDefinitions(): Prompt[] {
+  // Helper to get MCP Prompt definitions from registry
+  return toolRegistry
+    .filter((tool) => tool.prompt)
+    .map((tool) => ({
+      arguments:
+        tool.prompt!.arguments || extractPromptArguments(tool.zodSchema),
+      description: tool.prompt!.description,
+      name: tool.name,
+    }));
+}
+
+export function getPromptMessage(
+  toolName: string,
+  args: Record<string, unknown>,
+): string {
+  const tool = toolRegistry.find((t) => t.name === toolName);
+  if (!tool?.prompt) {
+    throw new Error(`No prompt defined for tool: ${toolName}`);
+  }
+  const paramStrings: string[] = [];
+
+  if (args.prompt) {
+    paramStrings.push(args.prompt as string);
+  }
+
+  Object.entries(args).forEach(([key, value]) => {
+    if (
+      key !== "prompt" &&
+      value !== undefined &&
+      value !== null &&
+      value !== false
+    ) {
+      if (typeof value === "boolean" && value) {
+        paramStrings.push(`[${key}]`);
+      } else if (typeof value !== "boolean") {
+        paramStrings.push(`(${key}: ${value})`);
+      }
+    }
+  });
+
+  return `Use the ${toolName} tool${paramStrings.length > 0 ? ": " + paramStrings.join(" ") : ""}`;
+}
+
+export function getToolDefinitions(): Tool[] {
+  // get Tool definitions from registry
+  return toolRegistry.map((tool) => {
+    const raw = zodToJsonSchema(tool.zodSchema, tool.name) as {
+      definitions?: Record<string, unknown>;
+      properties?: Record<string, unknown>;
+      required?: string[];
+    };
+    const def = (raw.definitions?.[tool.name] ?? raw) as {
+      properties?: Record<string, unknown>;
+      required?: string[];
+    };
+    const inputSchema: Tool["inputSchema"] = {
+      properties: def.properties || {},
+      required: def.required || [],
+      type: "object",
+    };
+
+    return {
+      description: tool.description,
+      inputSchema,
+      name: tool.name,
+    };
+  });
+}
+
+export function toolExists(toolName: string): boolean {
+  return toolRegistry.some((t) => t.name === toolName);
+}
+
+function extractPromptArguments(zodSchema: ZodTypeAny): Array<{
+  description: string;
+  name: string;
+  required: boolean;
+}> {
+  const jsonSchema = zodToJsonSchema(zodSchema) as {
+    properties?: Record<string, { description?: string }>;
+    required?: string[];
+  };
+  const properties = jsonSchema.properties || {};
+  const required = jsonSchema.required || [];
+
+  return Object.entries(properties).map(([name, prop]) => ({
+    description: prop.description || `${name} parameter`,
+    name,
+    required: required.includes(name),
+  }));
+}

package/src/tools/simple-tools.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+import { UnifiedTool } from "./registry.js";
+
+const pingArgsSchema = z.object({
+  prompt: z.string().default("").describe("Message to echo "),
+});
+
+export const pingTool: UnifiedTool = {
+  category: "simple",
+  description: "Echo",
+  execute: async (args) => {
+    const message = args.prompt || args.message || "Pong!";
+    // Return message directly to avoid cross-platform issues with echo command
+    return message as string;
+  },
+  name: "ping",
+  prompt: {
+    description: "Echo test message with structured response.",
+  },
+  zodSchema: pingArgsSchema,
+};
+
+const helpArgsSchema = z.object({});
+
+export const helpTool: UnifiedTool = {
+  category: "simple",
+  description: "receive help information",
+  execute: async () => {
+    return "Help information for Coolors MCP:\n\nAvailable tools for color manipulation, theme generation, and CSS refactoring.\nSee documentation for details.";
+  },
+  name: "Help",
+  prompt: {
+    description: "receive help information",
+  },
+  zodSchema: helpArgsSchema,
+};

package/src/tools/theme-matching.tools.ts

@@ -0,0 +1,334 @@
+/**
+ * Theme Matching Tools
+ * Tools for matching colors to theme variables and refactoring CSS
+ */
+
+import { z } from "zod";
+
+import { corePaletteFromRgb, parseColor, rgbToHex } from "../color/index.js";
+import {
+  type ColorContext,
+  findBatchMatches,
+  findClosestThemeColor,
+  generateRefactoringReport,
+  parseThemeVariables,
+  refactorCss,
+} from "../theme/index.js";
+
+/**
+ * Match Theme Color Tool
+ */
+export const matchThemeColorTool = {
+  description: "Find the closest matching theme variable for a given color",
+  execute: async (args: {
+    color: string;
+    context?: ColorContext;
+    minConfidence?: number;
+    themeCSS: string;
+  }) => {
+    // Parse theme variables from CSS
+    const themeVariables = parseThemeVariables(args.themeCSS);
+
+    // Find closest match
+    const match = findClosestThemeColor(args.color, themeVariables, {
+      contextType: args.context,
+    });
+
+    if (!match) {
+      return "No matching theme variable found";
+    }
+
+    const minConfidence = args.minConfidence ?? 70;
+    if (match.confidence < minConfidence) {
+      return `Best match below confidence threshold:
+Variable: ${match.variable}
+Distance: ${match.distance.toFixed(2)}
+Confidence: ${match.confidence}%
+
+Consider adding a new theme variable for this color.`;
+    }
+
+    let result = `Best Match:
+Variable: ${match.variable}
+Value: ${match.value}
+Distance: ${match.distance.toFixed(2)}
+Confidence: ${match.confidence}%`;
+
+    if (match.semanticRole) {
+      result += `\nSemantic Role: ${match.semanticRole}`;
+    }
+
+    if (match.accessibilityInfo) {
+      result += `\n\nAccessibility:
+Contrast with background: ${match.accessibilityInfo.contrastWithBackground.toFixed(2)}
+Contrast with foreground: ${match.accessibilityInfo.contrastWithForeground.toFixed(2)}
+Meets AA: ${match.accessibilityInfo.meetsAA ? "Yes" : "No"}
+Meets AAA: ${match.accessibilityInfo.meetsAAA ? "Yes" : "No"}`;
+    }
+
+    if (match.alternatives.length > 0) {
+      result += `\n\nAlternatives:`;
+      for (const alt of match.alternatives) {
+        result += `\n- ${alt.variable} (confidence: ${alt.confidence}%)`;
+      }
+    }
+
+    return result;
+  },
+  name: "match_theme_color",
+  parameters: z.object({
+    color: z.string().describe("Color to match (hex, rgb, hsl)"),
+    context: z
+      .enum(["text", "background", "border", "shadow", "accent", "decorative"])
+      .optional()
+      .describe("Usage context for better matching"),
+    minConfidence: z
+      .number()
+      .min(0)
+      .max(100)
+      .optional()
+      .default(70)
+      .describe("Minimum confidence threshold (0-100)"),
+    themeCSS: z.string().describe("CSS containing theme variables"),
+  }),
+};
+
+/**
+ * Refactor CSS with Theme Tool
+ */
+export const refactorCssWithThemeTool = {
+  description:
+    "Refactor CSS to use theme variables instead of hardcoded colors",
+  execute: async (args: {
+    css: string;
+    generateReport?: boolean;
+    minConfidence?: number;
+    preserveOriginal?: boolean;
+    themeCSS: string;
+  }) => {
+    // Parse theme variables
+    const themeVariables = parseThemeVariables(args.themeCSS);
+
+    // Refactor CSS
+    const result = refactorCss(args.css, themeVariables, {
+      addComments: args.preserveOriginal ?? true,
+      minConfidence: args.minConfidence ?? 70,
+      preserveOriginal: args.preserveOriginal ?? true,
+    });
+
+    let output = `Refactoring Complete!
+
+Statistics:
+- Total colors found: ${result.statistics.totalColors}
+- Colors replaced: ${result.statistics.replacedColors}
+- Average confidence: ${result.statistics.averageConfidence}%
+- Accessibility issues: ${result.statistics.accessibilityIssues}
+
+Refactored CSS:
+----------------------------------------
+${result.refactored}
+----------------------------------------`;
+
+    if (result.warnings.length > 0) {
+      output += `\n\nWarnings (${result.warnings.length}):`;
+      for (const warning of result.warnings.slice(0, 5)) {
+        output += `\n- ${warning.message}`;
+        if (warning.suggestion) {
+          output += `\n  Suggestion: ${warning.suggestion}`;
+        }
+      }
+      if (result.warnings.length > 5) {
+        output += `\n... and ${result.warnings.length - 5} more warnings`;
+      }
+    }
+
+    if (args.generateReport) {
+      output += `\n\n${generateRefactoringReport(result)}`;
+    }
+
+    return output;
+  },
+  name: "refactor_css_with_theme",
+  parameters: z.object({
+    css: z.string().describe("CSS content to refactor"),
+    generateReport: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Generate detailed refactoring report"),
+    minConfidence: z
+      .number()
+      .min(0)
+      .max(100)
+      .optional()
+      .default(70)
+      .describe("Minimum confidence for replacements"),
+    preserveOriginal: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Keep original values as comments"),
+    themeCSS: z.string().describe("CSS containing theme variables"),
+  }),
+};
+
+/**
+ * Match Theme Colors Batch Tool
+ */
+export const matchThemeColorsBatchTool = {
+  description: "Find theme matches for multiple colors at once",
+  execute: async (args: {
+    colors: string[];
+    context?: ColorContext;
+    themeCSS: string;
+  }) => {
+    // Parse theme variables
+    const themeVariables = parseThemeVariables(args.themeCSS);
+
+    // Find matches for all colors
+    const matches = findBatchMatches(args.colors, themeVariables, {
+      contextType: args.context,
+    });
+
+    let result = `Theme Color Matches:\n`;
+    let matchCount = 0;
+    let totalConfidence = 0;
+
+    for (const [color, match] of matches.entries()) {
+      if (match) {
+        matchCount++;
+        totalConfidence += match.confidence;
+        result += `\n${color} → ${match.variable} (${match.confidence}%)`;
+      } else {
+        result += `\n${color} → No match found`;
+      }
+    }
+
+    result += `\n\nSummary:
+- Matched: ${matchCount}/${args.colors.length}
+- Average confidence: ${matchCount > 0 ? Math.round(totalConfidence / matchCount) : 0}%`;
+
+    return result;
+  },
+  name: "match_theme_colors_batch",
+  parameters: z.object({
+    colors: z
+      .array(z.string())
+      .min(1)
+      .max(50)
+      .describe("Array of colors to match"),
+    context: z
+      .enum(["text", "background", "border", "shadow", "accent", "decorative"])
+      .optional()
+      .describe("Usage context for all colors"),
+    themeCSS: z.string().describe("CSS containing theme variables"),
+  }),
+};
+
+/**
+ * Generate Theme CSS Tool
+ */
+export const generateThemeCssTool = {
+  description:
+    "Generate CSS custom properties for a complete theme from a source color",
+  execute: async (args: {
+    includeTones?: number[];
+    prefix?: string;
+    sourceColor: string;
+  }) => {
+    const source = parseColor(args.sourceColor);
+    if (!source) {
+      return `Invalid color format: ${args.sourceColor}`;
+    }
+
+    const corePalette = corePaletteFromRgb(source);
+    const tones = args.includeTones || [
+      0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100,
+    ];
+    const prefix = args.prefix || "color";
+
+    let css = `:root {\n`;
+
+    // Generate primary palette
+    css += `  /* Primary Colors */\n`;
+    for (const tone of tones) {
+      const color = rgbToHex(corePalette.primary.tone(tone));
+      css += `  --${prefix}-primary-${tone}: ${color};\n`;
+    }
+
+    // Generate secondary palette
+    css += `\n  /* Secondary Colors */\n`;
+    for (const tone of tones) {
+      const color = rgbToHex(corePalette.secondary.tone(tone));
+      css += `  --${prefix}-secondary-${tone}: ${color};\n`;
+    }
+
+    // Generate tertiary palette
+    css += `\n  /* Tertiary Colors */\n`;
+    for (const tone of tones) {
+      const color = rgbToHex(corePalette.tertiary.tone(tone));
+      css += `  --${prefix}-tertiary-${tone}: ${color};\n`;
+    }
+
+    // Generate error palette
+    css += `\n  /* Error Colors */\n`;
+    for (const tone of tones) {
+      const color = rgbToHex(corePalette.error.tone(tone));
+      css += `  --${prefix}-error-${tone}: ${color};\n`;
+    }
+
+    // Generate neutral palette
+    css += `\n  /* Neutral Colors */\n`;
+    for (const tone of tones) {
+      const color = rgbToHex(corePalette.neutral.tone(tone));
+      css += `  --${prefix}-neutral-${tone}: ${color};\n`;
+    }
+
+    // Generate neutral variant palette
+    css += `\n  /* Neutral Variant Colors */\n`;
+    for (const tone of tones) {
+      const color = rgbToHex(corePalette.neutralVariant.tone(tone));
+      css += `  --${prefix}-neutral-variant-${tone}: ${color};\n`;
+    }
+
+    css += `}\n\n`;
+
+    // Add semantic mappings
+    css += `/* Semantic Color Mappings (Light Theme) */\n`;
+    css += `:root {\n`;
+    css += `  --${prefix}-primary: var(--${prefix}-primary-40);\n`;
+    css += `  --${prefix}-on-primary: var(--${prefix}-primary-100);\n`;
+    css += `  --${prefix}-primary-container: var(--${prefix}-primary-90);\n`;
+    css += `  --${prefix}-on-primary-container: var(--${prefix}-primary-10);\n`;
+    css += `  \n`;
+    css += `  --${prefix}-secondary: var(--${prefix}-secondary-40);\n`;
+    css += `  --${prefix}-on-secondary: var(--${prefix}-secondary-100);\n`;
+    css += `  --${prefix}-secondary-container: var(--${prefix}-secondary-90);\n`;
+    css += `  --${prefix}-on-secondary-container: var(--${prefix}-secondary-10);\n`;
+    css += `  \n`;
+    css += `  --${prefix}-background: var(--${prefix}-neutral-99);\n`;
+    css += `  --${prefix}-on-background: var(--${prefix}-neutral-10);\n`;
+    css += `  --${prefix}-surface: var(--${prefix}-neutral-99);\n`;
+    css += `  --${prefix}-on-surface: var(--${prefix}-neutral-10);\n`;
+    css += `}\n`;
+
+    return css;
+  },
+  name: "generate_theme_css",
+  parameters: z.object({
+    includeTones: z
+      .array(z.number())
+      .optional()
+      .describe(
+        "Tone values to include (default: 0,10,20,30,40,50,60,70,80,90,95,99,100)",
+      ),
+    prefix: z
+      .string()
+      .optional()
+      .default("color")
+      .describe(
+        "Prefix for CSS variables (e.g., 'color' → --color-primary-50)",
+      ),
+    sourceColor: z.string().describe("Source color for theme generation"),
+  }),
+};

package/src/types.ts

@@ -0,0 +1,182 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { GetPromptResult, Root } from "@modelcontextprotocol/sdk/types.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type AudioContent = {
+  data: string;
+  mimeType: string;
+  type: "audio";
+};
+
+export type Content =
+  | AudioContent
+  | ImageContent
+  | ResourceContent
+  | ResourceLink
+  | TextContent;
+
+export type ContentResult = {
+  content: Content[];
+  isError?: boolean;
+};
+
+export type Context<T extends CoolorsMCPSessionAuth> = {
+  client: {
+    version: ReturnType<Server["getClientVersion"]>;
+  };
+  log: {
+    debug: (message: string, data?: SerializableValue) => void;
+    error: (message: string, data?: SerializableValue) => void;
+    info: (message: string, data?: SerializableValue) => void;
+    warn: (message: string, data?: SerializableValue) => void;
+  };
+  reportProgress: (progress: Progress) => Promise<void>;
+  session: T | undefined;
+  streamContent: (content: Content | Content[]) => Promise<void>;
+};
+
+export type CoolorsMCPEvents = {
+  connect: (event: { session: any }) => void;
+  disconnect: (event: { session: any }) => void;
+};
+
+export type CoolorsMCPSessionAuth = Record<string, unknown> | undefined;
+
+export type CoolorsMCPSessionData = Record<string, unknown>;
+
+export type CoolorsMCPSessionEvents = {
+  error: (event: { error: Error }) => void;
+  ready: () => void;
+  rootsChanged: (event: { roots: Root[] }) => void;
+};
+
+export type ImageContent = {
+  data: string;
+  mimeType: string;
+  type: "image";
+};
+
+export type Literal = boolean | null | number | string | undefined;
+
+export interface Logger {
+  debug(...args: unknown[]): void;
+
+  error(...args: unknown[]): void;
+
+  info(...args: unknown[]): void;
+
+  log(...args: unknown[]): void;
+
+  warn(...args: unknown[]): void;
+}
+
+export type LoggingLevel =
+  | "alert"
+  | "critical"
+  | "debug"
+  | "emergency"
+  | "error"
+  | "info"
+  | "notice"
+  | "warning";
+
+export type Progress = {
+  progress: number;
+  total?: number;
+};
+
+export type PromptResult = Pick<GetPromptResult, "messages"> | string;
+
+export type ResourceContent = {
+  resource: {
+    blob?: string;
+    mimeType?: string;
+    text?: string;
+    uri: string;
+  };
+  type: "resource";
+};
+
+export type ResourceLink = {
+  description?: string;
+  mimeType?: string;
+  name: string;
+  title?: string;
+  type: "resource_link";
+  uri: string;
+};
+
+export type SerializableValue =
+  | { [key: string]: SerializableValue }
+  | Literal
+  | SerializableValue[];
+
+export type ServerOptions<T extends CoolorsMCPSessionAuth> = {
+  authenticate?: (request: unknown) => Promise<T>;
+  health?: {
+    enabled?: boolean;
+    message?: string;
+    path?: string;
+    status?: number;
+  };
+  instructions?: string;
+  logger?: Logger;
+  name: string;
+  ping?: {
+    enabled?: boolean;
+    intervalMs?: number;
+    logLevel?: LoggingLevel;
+  };
+  roots?: {
+    enabled?: boolean;
+  };
+  utils?: {
+    formatInvalidParamsErrorMessage?: (
+      issues: readonly StandardSchemaV1.Issue[],
+    ) => string;
+  };
+  version: `${number}.${number}.${number}`;
+};
+
+export type TextContent = {
+  text: string;
+  type: "text";
+};
+
+export type Tool<
+  T extends CoolorsMCPSessionAuth,
+  Params extends ToolParameters = ToolParameters,
+> = {
+  annotations?: {
+    streamingHint?: boolean;
+  } & ToolAnnotations;
+  canAccess?: (auth: T) => boolean;
+  description?: string;
+
+  execute: (
+    args: StandardSchemaV1.InferOutput<Params>,
+    context: Context<T>,
+  ) => Promise<
+    | AudioContent
+    | ContentResult
+    | ImageContent
+    | ResourceContent
+    | ResourceLink
+    | string
+    | TextContent
+    | void
+  >;
+  name: string;
+  parameters?: Params;
+  timeoutMs?: number;
+};
+
+export type ToolAnnotations = {
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+  readOnlyHint?: boolean;
+  title?: string;
+};
+
+export type ToolParameters = StandardSchemaV1;

package/src/utils.ts

@@ -0,0 +1,22 @@
+/**
+ * Converts camelCase to snake_case for OAuth endpoint responses
+ */
+export function camelToSnakeCase(str: string): string {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+/**
+ * Converts an object with camelCase keys to snake_case keys
+ */
+export function convertObjectToSnakeCase(
+  obj: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const snakeKey = camelToSnakeCase(key);
+    result[snakeKey] = value;
+  }
+
+  return result;
+}