@trishchuk/coolors-mcp 1.0.0

package/src/color/utils.ts

@@ -0,0 +1,315 @@
+/**
+ * Utility functions for color manipulation and validation
+ */
+
+import type { HSL, HSV, RGB } from "./types.js";
+
+import { parseColor, rgbToHex, rgbToHsl, rgbToHsv } from "./conversions.js";
+
+/**
+ * Clamp HSL values to valid range
+ */
+export function clampHsl(hsl: HSL): HSL {
+  return {
+    h: clamp(hsl.h, 0, 360),
+    l: clamp(hsl.l, 0, 100),
+    s: clamp(hsl.s, 0, 100),
+  };
+}
+
+/**
+ * Clamp HSV values to valid range
+ */
+export function clampHsv(hsv: HSV): HSV {
+  return {
+    h: clamp(hsv.h, 0, 360),
+    s: clamp(hsv.s, 0, 100),
+    v: clamp(hsv.v, 0, 100),
+  };
+}
+
+/**
+ * Clamp RGB values to valid range
+ */
+export function clampRgb(rgb: RGB): RGB {
+  return {
+    b: clamp(rgb.b, 0, 255),
+    g: clamp(rgb.g, 0, 255),
+    r: clamp(rgb.r, 0, 255),
+  };
+}
+
+/**
+ * Darken a color by a percentage
+ * @param rgb The color to darken
+ * @param amount Amount to darken (0-100)
+ */
+export function darken(rgb: RGB, amount: number): RGB {
+  const hsl = rgbToHsl(rgb);
+  hsl.l = clamp(hsl.l - amount, 0, 100);
+  return parseColor(formatHsl(hsl)) || rgb;
+}
+
+/**
+ * Desaturate a color by a percentage
+ * @param rgb The color to desaturate
+ * @param amount Amount to desaturate (0-100)
+ */
+export function desaturate(rgb: RGB, amount: number): RGB {
+  const hsl = rgbToHsl(rgb);
+  hsl.s = clamp(hsl.s - amount, 0, 100);
+  return parseColor(formatHsl(hsl)) || rgb;
+}
+
+/**
+ * Format color to various string representations
+ */
+export function formatColor(
+  rgb: RGB,
+  format: "hex" | "hsl" | "hsv" | "rgb" = "hex",
+): string {
+  switch (format) {
+    case "hex":
+      return rgbToHex(rgb);
+    case "hsl":
+      return formatHsl(rgbToHsl(rgb));
+    case "hsv": {
+      const hsv = rgbToHsv(rgb);
+      return `hsv(${hsv.h}, ${hsv.s}%, ${hsv.v}%)`;
+    }
+    case "rgb":
+      return formatRgb(rgb);
+    default:
+      return rgbToHex(rgb);
+  }
+}
+
+/**
+ * Format HSL color to string
+ */
+export function formatHsl(hsl: HSL, alpha?: number): string {
+  if (alpha !== undefined) {
+    return `hsla(${hsl.h}, ${hsl.s}%, ${hsl.l}%, ${alpha})`;
+  }
+  return `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`;
+}
+
+/**
+ * Format RGB color to string
+ */
+export function formatRgb(rgb: RGB, alpha?: number): string {
+  if (alpha !== undefined) {
+    return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})`;
+  }
+  return `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+}
+
+/**
+ * Get complementary color (opposite on color wheel)
+ */
+export function getComplementary(rgb: RGB): RGB {
+  const hsl = rgbToHsl(rgb);
+  hsl.h = (hsl.h + 180) % 360;
+  return parseColor(formatHsl(hsl)) || rgb;
+}
+
+/**
+ * Calculate contrast ratio between two colors
+ * Based on WCAG 2.0 formula
+ */
+export function getContrastRatio(color1: RGB, color2: RGB): number {
+  const lum1 = getLuminance(color1);
+  const lum2 = getLuminance(color2);
+
+  const lighter = Math.max(lum1, lum2);
+  const darker = Math.min(lum1, lum2);
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Calculate relative luminance of an RGB color
+ * Based on WCAG 2.0 formula
+ */
+export function getLuminance(rgb: RGB): number {
+  const rsRGB = rgb.r / 255;
+  const gsRGB = rgb.g / 255;
+  const bsRGB = rgb.b / 255;
+
+  const r =
+    rsRGB <= 0.03928 ? rsRGB / 12.92 : Math.pow((rsRGB + 0.055) / 1.055, 2.4);
+  const g =
+    gsRGB <= 0.03928 ? gsRGB / 12.92 : Math.pow((gsRGB + 0.055) / 1.055, 2.4);
+  const b =
+    bsRGB <= 0.03928 ? bsRGB / 12.92 : Math.pow((bsRGB + 0.055) / 1.055, 2.4);
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * Invert a color
+ */
+export function invertColor(rgb: RGB): RGB {
+  return {
+    b: 255 - rgb.b,
+    g: 255 - rgb.g,
+    r: 255 - rgb.r,
+  };
+}
+
+/**
+ * Check if a color is considered "dark"
+ * Based on luminance threshold
+ */
+export function isDark(rgb: RGB, threshold: number = 0.5): boolean {
+  return getLuminance(rgb) < threshold;
+}
+
+/**
+ * Check if a color is considered "light"
+ * Based on luminance threshold
+ */
+export function isLight(rgb: RGB, threshold: number = 0.5): boolean {
+  return getLuminance(rgb) >= threshold;
+}
+
+/**
+ * Validate hexadecimal color string
+ */
+export function isValidHex(hex: string): boolean {
+  const cleanHex = hex.replace("#", "");
+  return /^[0-9A-Fa-f]{3}$|^[0-9A-Fa-f]{6}$/.test(cleanHex);
+}
+
+/**
+ * Validate HSL color values
+ */
+export function isValidHsl(hsl: HSL): boolean {
+  return (
+    hsl.h >= 0 &&
+    hsl.h <= 360 &&
+    hsl.s >= 0 &&
+    hsl.s <= 100 &&
+    hsl.l >= 0 &&
+    hsl.l <= 100
+  );
+}
+
+/**
+ * Validate HSV color values
+ */
+export function isValidHsv(hsv: HSV): boolean {
+  return (
+    hsv.h >= 0 &&
+    hsv.h <= 360 &&
+    hsv.s >= 0 &&
+    hsv.s <= 100 &&
+    hsv.v >= 0 &&
+    hsv.v <= 100
+  );
+}
+
+/**
+ * Validate RGB color values
+ */
+export function isValidRgb(rgb: RGB): boolean {
+  return (
+    rgb.r >= 0 &&
+    rgb.r <= 255 &&
+    rgb.g >= 0 &&
+    rgb.g <= 255 &&
+    rgb.b >= 0 &&
+    rgb.b <= 255
+  );
+}
+
+/**
+ * Lighten a color by a percentage
+ * @param rgb The color to lighten
+ * @param amount Amount to lighten (0-100)
+ */
+export function lighten(rgb: RGB, amount: number): RGB {
+  const hsl = rgbToHsl(rgb);
+  hsl.l = clamp(hsl.l + amount, 0, 100);
+  return parseColor(formatHsl(hsl)) || rgb;
+}
+
+/**
+ * Check if contrast meets WCAG AA standard
+ * Normal text: 4.5:1, Large text: 3:1
+ */
+export function meetsContrastAA(
+  color1: RGB,
+  color2: RGB,
+  largeText: boolean = false,
+): boolean {
+  const ratio = getContrastRatio(color1, color2);
+  return largeText ? ratio >= 3 : ratio >= 4.5;
+}
+
+/**
+ * Check if contrast meets WCAG AAA standard
+ * Normal text: 7:1, Large text: 4.5:1
+ */
+export function meetsContrastAAA(
+  color1: RGB,
+  color2: RGB,
+  largeText: boolean = false,
+): boolean {
+  const ratio = getContrastRatio(color1, color2);
+  return largeText ? ratio >= 4.5 : ratio >= 7;
+}
+
+/**
+ * Mix two colors together
+ * @param color1 First color
+ * @param color2 Second color
+ * @param weight Weight of the first color (0-1)
+ */
+export function mixColors(color1: RGB, color2: RGB, weight: number = 0.5): RGB {
+  const w = clamp(weight, 0, 1);
+  const w2 = 1 - w;
+
+  return {
+    b: Math.round(color1.b * w + color2.b * w2),
+    g: Math.round(color1.g * w + color2.g * w2),
+    r: Math.round(color1.r * w + color2.r * w2),
+  };
+}
+
+/**
+ * Generate a random RGB color
+ */
+export function randomColor(): RGB {
+  return {
+    b: Math.floor(Math.random() * 256),
+    g: Math.floor(Math.random() * 256),
+    r: Math.floor(Math.random() * 256),
+  };
+}
+
+/**
+ * Saturate a color by a percentage
+ * @param rgb The color to saturate
+ * @param amount Amount to saturate (0-100)
+ */
+export function saturate(rgb: RGB, amount: number): RGB {
+  const hsl = rgbToHsl(rgb);
+  hsl.s = clamp(hsl.s + amount, 0, 100);
+  return parseColor(formatHsl(hsl)) || rgb;
+}
+
+/**
+ * Convert color to grayscale
+ */
+export function toGrayscale(rgb: RGB): RGB {
+  const gray = Math.round(0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b);
+  return { b: gray, g: gray, r: gray };
+}
+
+/**
+ * Clamp a number between min and max values
+ */
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export enum ColorFormat {
+  HEX = "hex",
+  HSL = "hsl",
+  RGB = "rgb",
+}

package/src/coolors-mcp.ts

@@ -0,0 +1,37 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { EventEmitter } from "events";
+import { StrictEventEmitter } from "strict-event-emitter-types";
+
+import { CoolorsMCPSession } from "./session.js";
+import {
+  CoolorsMCPEvents,
+  CoolorsMCPSessionAuth,
+  ServerOptions,
+  Tool,
+  ToolParameters,
+} from "./types.js";
+
+export class CoolorsMcp extends (EventEmitter as {
+  new (): StrictEventEmitter<EventEmitter, CoolorsMCPEvents>;
+}) {
+  #sessions: CoolorsMCPSession[] = [];
+  #tools: Tool<CoolorsMCPSessionAuth>[] = [];
+
+  constructor(public options: ServerOptions<CoolorsMCPSessionAuth>) {
+    super();
+  }
+
+  public addTool<Params extends ToolParameters>(
+    tool: Tool<CoolorsMCPSessionAuth, Params>,
+  ) {
+    this.#tools.push(tool as unknown as Tool<CoolorsMCPSessionAuth>);
+  }
+
+  public async start() {
+    const transport = new StdioServerTransport();
+    const session = new CoolorsMCPSession(this.options, this.#tools);
+    this.#sessions.push(session);
+    await session.connect(transport);
+    this.emit("connect", { session });
+  }
+}

package/src/examples/addition.ts

@@ -0,0 +1,333 @@
+/**
+ * Example CoolorsMCP server demonstrating core functionality plus streaming output.
+ *
+ * Features demonstrated:
+ * - Basic tool with type-safe parameters
+ * - Streaming-enabled tool for incremental output
+ * - Advanced tool annotations
+ *
+ * For a complete project template, see https://github.com/punkpeye/coolors-mcp-boilerplate
+ */
+import { type } from "arktype";
+import * as v from "valibot";
+import { z } from "zod";
+
+import { CoolorsMcp } from "../coolors-mcp.js";
+
+const server = new CoolorsMcp({
+  name: "Addition",
+  ping: {
+    // enabled: undefined,
+    // Automatically enabled/disabled based on transport type
+    // Using a longer interval to reduce log noise
+    intervalMs: 10000, // default is 5000ms
+    // Reduce log verbosity
+    logLevel: "debug", // default
+  },
+  roots: {
+    // You can explicitly disable roots support if needed
+    // enabled: false,
+  },
+  version: "1.0.0",
+});
+
+// --- Zod Example ---
+const AddParamsZod = z.object({
+  a: z.number().describe("The first number"),
+  b: z.number().describe("The second number"),
+});
+
+server.addTool({
+  annotations: {
+    openWorldHint: false, // This tool doesn't interact with external systems
+    readOnlyHint: true, // This tool doesn't modify anything
+    title: "Addition (Zod)",
+  },
+  description: "Add two numbers (using Zod schema)",
+  execute: async (args) => {
+    // args is typed as { a: number, b: number }
+    console.log(`[Zod] Adding ${args.a} and ${args.b}`);
+    return String(args.a + args.b);
+  },
+  name: "add-zod",
+  parameters: AddParamsZod,
+});
+
+// --- ArkType Example ---
+const AddParamsArkType = type({
+  a: "number",
+  b: "number",
+});
+
+server.addTool({
+  annotations: {
+    destructiveHint: true, // This would perform destructive operations
+    idempotentHint: true, // But operations can be repeated safely
+    openWorldHint: true, // Interacts with external systems
+    readOnlyHint: false, // Example showing a modifying tool
+    title: "Addition (ArkType)",
+  },
+  description: "Add two numbers (using ArkType schema)",
+  execute: async (args, { log }) => {
+    // args is typed as { a: number, b: number } based on AddParamsArkType.infer
+    console.log(`[ArkType] Adding ${args.a} and ${args.b}`);
+
+    // Demonstrate long-running operation that might need a timeout
+    log.info("Starting calculation with potential delay...");
+
+    // Simulate a complex calculation process
+    if (args.a > 1000 || args.b > 1000) {
+      log.warn("Large numbers detected, operation might take longer");
+      // In a real implementation, this delay might be a slow operation
+      await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+
+    return String(args.a + args.b);
+  },
+  name: "add-arktype",
+  parameters: AddParamsArkType,
+  // Will abort execution after 2s
+  timeoutMs: 2000,
+});
+
+// --- Valibot Example ---
+const AddParamsValibot = v.object({
+  a: v.number("The first number"),
+  b: v.number("The second number"),
+});
+
+server.addTool({
+  annotations: {
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: "Addition (Valibot)",
+  },
+  description: "Add two numbers (using Valibot schema)",
+  execute: async (args) => {
+    console.log(`[Valibot] Adding ${args.a} and ${args.b}`);
+    return String(args.a + args.b);
+  },
+  name: "add-valibot",
+  parameters: AddParamsValibot,
+});
+
+server.addResource({
+  async load() {
+    return {
+      text: "Example log content",
+    };
+  },
+  mimeType: "text/plain",
+  name: "Application Logs",
+  uri: "file:///logs/app.log",
+});
+
+server.addTool({
+  annotations: {
+    openWorldHint: false,
+    readOnlyHint: true,
+    streamingHint: true,
+  },
+  description: "Generate a poem line by line with streaming output",
+  execute: async (args, context) => {
+    const { theme } = args;
+    const lines = [
+      `Poem about ${theme} - line 1`,
+      `Poem about ${theme} - line 2`,
+      `Poem about ${theme} - line 3`,
+      `Poem about ${theme} - line 4`,
+    ];
+
+    for (const line of lines) {
+      await context.streamContent({
+        text: line,
+        type: "text",
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+
+    return;
+  },
+  name: "stream-poem",
+  parameters: z.object({
+    theme: z.string().describe("Theme for the poem"),
+  }),
+});
+
+server.addTool({
+  annotations: {
+    openWorldHint: false,
+    readOnlyHint: false,
+  },
+  description: "Test progress reporting without buffering delays",
+  execute: async (args, { reportProgress }) => {
+    console.log("Testing progress reporting fix for HTTP Stream buffering...");
+
+    await reportProgress({ progress: 0, total: 100 });
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    await reportProgress({ progress: 25, total: 100 });
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    await reportProgress({ progress: 75, total: 100 });
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    // This progress should be received immediately
+    await reportProgress({ progress: 100, total: 100 });
+
+    return `Buffering test completed for ${args.testCase}`;
+  },
+  name: "test-buffering-fix",
+  parameters: z.object({
+    testCase: z.string().describe("Test case description"),
+  }),
+});
+
+server.addPrompt({
+  arguments: [
+    {
+      description: "Git diff or description of changes",
+      name: "changes",
+      required: true,
+    },
+  ],
+  description: "Generate a Git commit message",
+  load: async (args) => {
+    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
+  },
+  name: "git-commit",
+});
+
+server.addResourceTemplate({
+  arguments: [
+    {
+      description: "Documentation section to retrieve",
+      name: "section",
+      required: true,
+    },
+  ],
+  description: "Get project documentation",
+  load: async (args) => {
+    const docs = {
+      "api-reference":
+        "# API Reference\n\n## Authentication\nAll API requests require a valid API key in the Authorization header.\n\n## Endpoints\n- GET /users - List all users\n- POST /users - Create new user",
+      deployment:
+        "# Deployment Guide\n\nTo deploy this application:\n\n1. Build the project: `npm run build`\n2. Set environment variables\n3. Deploy to your hosting platform",
+      "getting-started":
+        "# Getting Started\n\nWelcome to our project! Follow these steps to set up your development environment:\n\n1. Clone the repository\n2. Install dependencies with `npm install`\n3. Run `npm start` to begin",
+    };
+
+    return {
+      text:
+        docs[args.section as keyof typeof docs] ||
+        "Documentation section not found",
+    };
+  },
+  mimeType: "text/markdown",
+  name: "Project Documentation",
+  uriTemplate: "docs://project/{section}",
+});
+
+server.addTool({
+  annotations: {
+    openWorldHint: false,
+    readOnlyHint: true,
+    title: "Get Documentation (Embedded)",
+  },
+  description:
+    "Retrieve project documentation using embedded resources - demonstrates the new embedded() feature",
+  execute: async (args) => {
+    return {
+      content: [
+        {
+          resource: await server.embedded(`docs://project/${args.section}`),
+          type: "resource",
+        },
+      ],
+    };
+  },
+  name: "get-documentation",
+  parameters: z.object({
+    section: z
+      .enum(["getting-started", "api-reference", "deployment"])
+      .describe("Documentation section to retrieve"),
+  }),
+});
+
+// Select transport type based on command line arguments
+const transportType = process.argv.includes("--http-stream")
+  ? "httpStream"
+  : "stdio";
+
+if (transportType === "httpStream") {
+  // Start with HTTP streaming transport
+  const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 8080;
+
+  server.start({
+    httpStream: {
+      port: PORT,
+    },
+    transportType: "httpStream",
+  });
+
+  console.log(
+    `HTTP Stream MCP server is running at http://localhost:${PORT}/mcp`,
+  );
+  console.log("Use StreamableHTTPClientTransport to connect to this server");
+  console.log("For example:");
+  console.log(`
+  import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+  import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+  
+  const client = new Client(
+    {
+      name: "example-client",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+  
+  const transport = new StreamableHTTPClientTransport(
+    new URL("http://localhost:${PORT}/mcp"),
+  );
+  
+  await client.connect(transport);
+  `);
+} else if (process.argv.includes("--explicit-ping-config")) {
+  server.start({
+    transportType: "stdio",
+  });
+
+  console.log(
+    "Started stdio transport with explicit ping configuration from server options",
+  );
+} else if (process.argv.includes("--disable-roots")) {
+  // Example of disabling roots at runtime
+  const serverWithDisabledRoots = new CoolorsMcp({
+    name: "Addition (No Roots)",
+    ping: {
+      intervalMs: 10000,
+      logLevel: "debug",
+    },
+    roots: {
+      enabled: false,
+    },
+    version: "1.0.0",
+  });
+
+  serverWithDisabledRoots.start({
+    transportType: "stdio",
+  });
+
+  console.log("Started stdio transport with roots support disabled");
+} else {
+  // Disable by default for:
+  server.start({
+    transportType: "stdio",
+  });
+
+  console.log("Started stdio transport with ping disabled by default");
+}