@trishchuk/coolors-mcp 1.0.0

package/src/examples/color-demo.ts

@@ -0,0 +1,125 @@
+/**
+ * Example demonstrating the color utilities module
+ */
+
+import {
+  areColorsSimilar,
+  // Distance metrics
+  colorDistance,
+  darken,
+  findMostSimilarColor,
+  getContrastRatio,
+
+  // Utility functions
+  getLuminance,
+  hexToRgb,
+  lighten,
+  meetsContrastAA,
+  mixColors,
+  // Types
+  type RGB,
+  // Conversion functions
+  rgbToHex,
+  rgbToHsl,
+  rgbToLab,
+} from "../color/index.js";
+
+// Example colors
+const red: RGB = { b: 0, g: 0, r: 255 };
+const blue: RGB = { b: 255, g: 0, r: 0 };
+const green: RGB = { b: 0, g: 255, r: 0 };
+const white: RGB = { b: 255, g: 255, r: 255 };
+const black: RGB = { b: 0, g: 0, r: 0 };
+
+console.log("=== Color Conversions ===");
+console.log("Red to Hex:", rgbToHex(red)); // #ff0000
+console.log("Hex to RGB:", hexToRgb("#00ff00")); // { r: 0, g: 255, b: 0 }
+console.log("Red to HSL:", rgbToHsl(red)); // { h: 0, s: 100, l: 50 }
+console.log("Red to LAB:", rgbToLab(red)); // L*a*b* color space
+
+console.log("\n=== Color Distance Metrics ===");
+console.log("Distance Red-Blue (Delta E 2000):", colorDistance(red, blue));
+console.log("Distance Red-Green (Delta E 2000):", colorDistance(red, green));
+console.log(
+  "Are Red and slightly darker Red similar?",
+  areColorsSimilar(red, { b: 5, g: 5, r: 250 }),
+);
+
+// Find most similar color from a palette
+const palette: RGB[] = [
+  { b: 0, g: 0, r: 200 }, // Dark red
+  { b: 0, g: 200, r: 0 }, // Dark green
+  { b: 200, g: 0, r: 0 }, // Dark blue
+  { b: 100, g: 100, r: 255 }, // Light red
+];
+
+const target: RGB = { b: 50, g: 50, r: 255 }; // Reddish color
+const mostSimilar = findMostSimilarColor(target, palette);
+console.log("Most similar to reddish:", mostSimilar);
+
+console.log("\n=== Color Utilities ===");
+console.log("Luminance of white:", getLuminance(white)); // ~1.0
+console.log("Luminance of black:", getLuminance(black)); // 0.0
+console.log("Contrast ratio (black/white):", getContrastRatio(black, white)); // 21:1
+console.log("Meets AA standard?", meetsContrastAA(black, white)); // true
+
+console.log("\n=== Color Manipulation ===");
+const lightRed = lighten(red, 20);
+console.log("Lightened red:", lightRed);
+
+const darkBlue = darken(blue, 30);
+console.log("Darkened blue:", darkBlue);
+
+const purple = mixColors(red, blue, 0.5);
+console.log("Mix red and blue (purple):", purple);
+
+console.log("\n=== Advanced Examples ===");
+
+// Example 1: Check if a text color has enough contrast
+function checkTextContrast(textColor: RGB, backgroundColor: RGB): void {
+  const ratio = getContrastRatio(textColor, backgroundColor);
+  const meetsAA = meetsContrastAA(textColor, backgroundColor);
+  const meetsAAA = ratio >= 7.0; // AAA standard for normal text
+
+  console.log(`Contrast ratio: ${ratio.toFixed(2)}:1`);
+  console.log(`WCAG AA: ${meetsAA ? "✓" : "✗"}`);
+  console.log(`WCAG AAA: ${meetsAAA ? "✓" : "✗"}`);
+}
+
+console.log("\nChecking dark gray on white:");
+checkTextContrast({ b: 85, g: 85, r: 85 }, white);
+
+// Example 2: Find perceptually different colors
+function findDistinctColors(baseColor: RGB, candidates: RGB[]): RGB[] {
+  return candidates.filter(
+    (color) => colorDistance(baseColor, color, { metric: "deltaE2000" }) > 50,
+  );
+}
+
+const distinctFromRed = findDistinctColors(red, palette);
+console.log("\nColors distinct from red:", distinctFromRed);
+
+// Example 3: Create a color scheme
+function createMonochromaticScheme(baseColor: RGB, steps: number = 5): RGB[] {
+  const scheme: RGB[] = [];
+  const stepSize = 100 / (steps - 1);
+
+  for (let i = 0; i < steps; i++) {
+    const amount = stepSize * i - 50; // -50 to +50
+    if (amount < 0) {
+      scheme.push(darken(baseColor, Math.abs(amount)));
+    } else if (amount > 0) {
+      scheme.push(lighten(baseColor, amount));
+    } else {
+      scheme.push(baseColor);
+    }
+  }
+
+  return scheme;
+}
+
+const blueScheme = createMonochromaticScheme(blue, 5);
+console.log("\nMonochromatic blue scheme:");
+blueScheme.forEach((color, i) => {
+  console.log(`  Step ${i + 1}:`, rgbToHex(color));
+});

package/src/examples/custom-logger.ts

@@ -0,0 +1,201 @@
+/**
+ * Example CoolorsMCP server demonstrating custom logger implementations.
+ *
+ * Features demonstrated:
+ * - Simple custom logger implementation
+ * - File-based logging example
+ * - Winston logger adapter
+ * - Pino logger adapter
+ *
+ */
+
+import { z } from "zod";
+
+import { CoolorsMcp, Logger } from "../coolors-mcp.js";
+
+// Example 1: Simple Custom Logger Implementation
+class SimpleCustomLogger implements Logger {
+  debug(...args: unknown[]): void {
+    console.log("[CUSTOM DEBUG]", new Date().toISOString(), ...args);
+  }
+
+  error(...args: unknown[]): void {
+    console.error("[CUSTOM ERROR]", new Date().toISOString(), ...args);
+  }
+
+  info(...args: unknown[]): void {
+    console.info("[CUSTOM INFO]", new Date().toISOString(), ...args);
+  }
+
+  log(...args: unknown[]): void {
+    console.log("[CUSTOM LOG]", new Date().toISOString(), ...args);
+  }
+
+  warn(...args: unknown[]): void {
+    console.warn("[CUSTOM WARN]", new Date().toISOString(), ...args);
+  }
+}
+
+// Example 2: File-based Logger
+// class FileLogger implements Logger {
+//   debug(...args: unknown[]): void {
+//     this.logToFile('DEBUG', ...args);
+//   }
+
+//   error(...args: unknown[]): void {
+//     this.logToFile('ERROR', ...args);
+//   }
+
+//   info(...args: unknown[]): void {
+//     this.logToFile('INFO', ...args);
+//   }
+
+//   log(...args: unknown[]): void {
+//     this.logToFile('LOG', ...args);
+//   }
+
+//   warn(...args: unknown[]): void {
+//     this.logToFile('WARN', ...args);
+//   }
+
+//   private logToFile(level: string, ...args: unknown[]): void {
+//     const timestamp = new Date().toISOString();
+//     const message = `[${timestamp}] [${level}] ${args.map(arg =>
+//       typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+//     ).join(' ')}\n`;
+
+//     // In a real implementation, you might use fs.appendFile or a logging library
+//     console.log(message.trim());
+//   }
+// }
+
+// Example 3: Winston Logger Adapter
+// To use this example, install winston: npm install winston
+// import winston from 'winston';
+
+// class WinstonLoggerAdapter implements Logger {
+//   private winston: winston.Logger;
+
+//   constructor() {
+//     this.winston = winston.createLogger({
+//       level: 'debug',
+//       format: winston.format.combine(
+//         winston.format.timestamp(),
+//         winston.format.errors({ stack: true }),
+//         winston.format.json()
+//       ),
+//       transports: [
+//         new winston.transports.Console({
+//           format: winston.format.combine(
+//             winston.format.colorize(),
+//             winston.format.simple()
+//           )
+//         }),
+//         new winston.transports.File({ filename: 'coolors-mcp.log' })
+//       ]
+//     });
+//   }
+
+//   debug(...args: unknown[]): void {
+//     this.winston.debug(this.formatArgs(args));
+//   }
+
+//   error(...args: unknown[]): void {
+//     this.winston.error(this.formatArgs(args));
+//   }
+
+//   info(...args: unknown[]): void {
+//     this.winston.info(this.formatArgs(args));
+//   }
+
+//   log(...args: unknown[]): void {
+//     this.winston.info(this.formatArgs(args));
+//   }
+
+//   warn(...args: unknown[]): void {
+//     this.winston.warn(this.formatArgs(args));
+//   }
+
+//   private formatArgs(args: unknown[]): string {
+//     return args.map(arg =>
+//       typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+//     ).join(' ');
+//   }
+// }
+
+// Example 4: Pino Logger Adapter
+// To use this example, install pino: npm install pino
+// import pino from 'pino';
+//
+// class PinoLoggerAdapter implements Logger {
+//   private pino: pino.Logger;
+//
+//   constructor() {
+//     this.pino = pino({
+//       level: 'debug',
+//       transport: {
+//         target: 'pino-pretty',
+//         options: {
+//           colorize: true,
+//           translateTime: 'SYS:standard',
+//           ignore: 'pid,hostname'
+//         }
+//       }
+//     });
+//   }
+//
+//   debug(...args: unknown[]): void {
+//     this.pino.debug(this.formatMessage(args));
+//   }
+//
+//   error(...args: unknown[]): void {
+//     this.pino.error(this.formatMessage(args));
+//   }
+//
+//   info(...args: unknown[]): void {
+//     this.pino.info(this.formatMessage(args));
+//   }
+//
+//   log(...args: unknown[]): void {
+//     this.pino.info(this.formatMessage(args));
+//   }
+//
+//   warn(...args: unknown[]): void {
+//     this.pino.warn(this.formatMessage(args));
+//   }
+//
+//   private formatMessage(args: unknown[]): string {
+//     return args.map(arg =>
+//       typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+//     ).join(' ');
+//   }
+// }
+
+// Choose which logger to use (uncomment the one you want to use)
+const logger = new SimpleCustomLogger();
+// const logger = new FileLogger();
+// const logger = new WinstonLoggerAdapter();
+// const logger = new PinoLoggerAdapter();
+
+const server = new CoolorsMcp({
+  logger: logger,
+  name: "custom-logger-example",
+  version: "1.0.0",
+});
+
+server.addTool({
+  description: "A test tool that demonstrates custom logging",
+  execute: async (args) => {
+    return `Received: ${args.message}`;
+  },
+  name: "test_tool",
+  parameters: z.object({
+    message: z.string().describe("A message to log"),
+  }),
+});
+
+// Start the server with stdio transport
+server.start({ transportType: "stdio" }).catch((error: unknown) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});

package/src/examples/oauth-server.ts

@@ -0,0 +1,113 @@
+/**
+ * Example CoolorsMCP server demonstrating OAuth well-known endpoint support.
+ *
+ * This example shows how to configure CoolorsMCP to serve OAuth discovery endpoints
+ * for both authorization server metadata and protected resource metadata.
+ *
+ * Run with: node dist/examples/oauth-server.js --transport http-stream --port 4111
+ * Then visit:
+ * - http://localhost:4111/.well-known/oauth-authorization-server
+ * - http://localhost:4111/.well-known/oauth-protected-resource
+ */
+
+import { CoolorsMcp } from "../coolors-mcp.js";
+
+const server = new CoolorsMcp({
+  name: "OAuth Example Server",
+  oauth: {
+    authorizationServer: {
+      authorizationEndpoint: "https://auth.example.com/oauth/authorize",
+      codeChallengeMethodsSupported: ["S256"],
+      // DPoP support
+      dpopSigningAlgValuesSupported: ["ES256", "RS256"],
+      grantTypesSupported: ["authorization_code", "refresh_token"],
+
+      introspectionEndpoint: "https://auth.example.com/oauth/introspect",
+      // Required fields
+      issuer: "https://auth.example.com",
+      // Optional fields
+      jwksUri: "https://auth.example.com/.well-known/jwks.json",
+      opPolicyUri: "https://example.com/policy",
+      opTosUri: "https://example.com/terms",
+      registrationEndpoint: "https://auth.example.com/oauth/register",
+      responseModesSupported: ["query", "fragment"],
+      responseTypesSupported: ["code"],
+      revocationEndpoint: "https://auth.example.com/oauth/revoke",
+      scopesSupported: ["read", "write", "admin"],
+      serviceDocumentation: "https://docs.example.com/oauth",
+      tokenEndpoint: "https://auth.example.com/oauth/token",
+      tokenEndpointAuthMethodsSupported: [
+        "client_secret_basic",
+        "client_secret_post",
+      ],
+      tokenEndpointAuthSigningAlgValuesSupported: ["RS256", "ES256"],
+
+      uiLocalesSupported: ["en-US", "es-ES"],
+    },
+    enabled: true,
+    protectedResource: {
+      authorizationDetailsTypesSupported: [
+        "payment_initiation",
+        "account_access",
+      ],
+      authorizationServers: ["https://auth.example.com"],
+      bearerMethodsSupported: ["header"],
+      dpopBoundAccessTokensRequired: false,
+      dpopSigningAlgValuesSupported: ["ES256", "RS256"],
+      jwksUri: "https://oauth-example-server.example.com/.well-known/jwks.json",
+      resource: "mcp://oauth-example-server",
+      resourceDocumentation: "https://docs.example.com/mcp-api",
+      resourceName: "OAuth Example API",
+      resourcePolicyUri: "https://example.com/resource-policy",
+      resourceSigningAlgValuesSupported: ["RS256", "ES256"],
+      resourceTosUri: "https://example.com/terms-of-service",
+      scopesSupported: ["read", "write", "admin"],
+      serviceDocumentation: "https://developer.example.com/api-docs",
+      tlsClientCertificateBoundAccessTokens: false,
+    },
+  },
+  version: "1.0.0",
+});
+
+// Add a simple tool to demonstrate the server functionality
+server.addTool({
+  description: "Get information about this OAuth-enabled MCP server",
+  execute: async () => {
+    return {
+      content: [
+        {
+          text: `This is an OAuth-enabled CoolorsMCP server!
+
+OAuth Discovery Endpoints:
+- Authorization Server: /.well-known/oauth-authorization-server
+- Protected Resource: /.well-known/oauth-protected-resource
+
+The server demonstrates how to configure OAuth metadata for MCP servers
+that need to integrate with OAuth 2.0 authorization flows.`,
+          type: "text",
+        },
+      ],
+    };
+  },
+  name: "get-server-info",
+});
+
+// Start the server
+await server.start({
+  httpStream: { port: 4111 },
+  transportType: "httpStream",
+});
+
+console.log(`
+🚀 OAuth Example Server is running!
+
+Try these endpoints:
+- MCP (HTTP Stream): http://localhost:4111/mcp
+- MCP (SSE): http://localhost:4111/sse
+- Health: http://localhost:4111/health
+- OAuth Authorization Server: http://localhost:4111/.well-known/oauth-authorization-server
+- OAuth Protected Resource: http://localhost:4111/.well-known/oauth-protected-resource
+
+The OAuth endpoints work with both SSE and HTTP Stream transports and return
+JSON metadata following RFC 8414 standards.
+`);

package/src/examples/session-context.ts

@@ -0,0 +1,269 @@
+/**
+ * Example demonstrating session context support in CoolorsMCP stdio transport
+ *
+ * This example demonstrates the fix for issue #144:
+ * Session context is now properly passed to tool execution handlers
+ * when using stdio transport with an authenticate function.
+ *
+ * To run this example:
+ * npx coolors-mcp dev src/examples/session-context.ts
+ */
+
+import { z } from "zod";
+
+import { CoolorsMcp } from "../coolors-mcp.js";
+
+interface UserSession {
+  [key: string]: unknown;
+  permissions: string[];
+  role: "admin" | "guest" | "user";
+  userId: string;
+  username: string;
+}
+
+const server = new CoolorsMcp<UserSession>({
+  authenticate: async (request) => {
+    if (!request) {
+      console.log(
+        "[Auth] Authenticating stdio transport using environment variables",
+      );
+
+      const userId = process.env.USER_ID || "default-user";
+      const username = process.env.USERNAME || "Anonymous";
+      const role =
+        (process.env.USER_ROLE as "admin" | "guest" | "user") || "guest";
+      // Mock permissions based on role
+      const permissions =
+        role === "admin"
+          ? ["read", "write", "delete", "admin"]
+          : role === "user"
+            ? ["read", "write"]
+            : ["read"];
+      const session: UserSession = {
+        authenticatedAt: new Date().toISOString(),
+        permissions,
+        role,
+        userId,
+        username,
+      };
+
+      console.log(`[Auth] Authenticated user: ${username} (${role})`);
+
+      return session;
+    }
+
+    // For HTTP transport (request contains headers)
+    console.log("[Auth] Authenticating HTTP transport using headers");
+
+    const authHeader = request.headers["authorization"] as string;
+
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      throw new Response("Missing or invalid authorization header", {
+        status: 401,
+      });
+    }
+
+    const token = authHeader.substring(7);
+
+    // Mock token validation (in real implementation, validate against your auth service)
+    if (token === "admin-token") {
+      return {
+        authenticatedAt: new Date().toISOString(),
+        permissions: ["read", "write", "delete", "admin"],
+        role: "admin" as const,
+        userId: "admin-001",
+        username: "Administrator",
+      };
+    } else if (token === "user-token") {
+      return {
+        authenticatedAt: new Date().toISOString(),
+        permissions: ["read", "write"],
+        role: "user" as const,
+        userId: "user-001",
+        username: "Regular User",
+      };
+    }
+
+    throw new Response("Invalid token", { status: 401 });
+  },
+  name: "Session Context Demo",
+  version: "1.0.0",
+});
+
+// Tool that demonstrates session context access
+server.addTool({
+  description: "Get information about the current authenticated user",
+  execute: async (_args, context) => {
+    if (!context.session)
+      return "No session context available (this shouldn't happen after the fix!)";
+
+    const { session } = context;
+
+    return `✓ Session Context Available!
+    
+User Info:
+- User ID: ${session.userId}
+- Username: ${session.username}  
+- Role: ${session.role}
+- Permissions: ${session.permissions.join(", ")}
+- Authenticated At: ${session.authenticatedAt}`;
+  },
+  name: "whoami",
+});
+
+// Tool that demonstrates role-based access
+server.addTool({
+  description: "Perform an admin-only operation (requires admin role)",
+  execute: async (args, context) => {
+    if (!context.session)
+      return "No session context - cannot verify permissions";
+    if (context.session.role !== "admin")
+      return `Access denied. Current role: ${context.session.role}, required: admin`;
+    if (!context.session.permissions.includes("admin"))
+      return "Insufficient permissions for admin operations";
+
+    return `✓ Admin operation "${args.action}" executed successfully by ${context.session.username}`;
+  },
+  name: "admin-operation",
+  parameters: z.object({
+    action: z.string().describe("The admin action to perform"),
+  }),
+});
+
+// Tool that demonstrates permission checks
+server.addTool({
+  description: "Check what permissions the current user has",
+  execute: async (args, context) => {
+    if (!context.session) return "No session context available";
+
+    const hasPermission = context.session.permissions.includes(args.operation);
+
+    return `Permission Check for "${args.operation}":
+${hasPermission ? "✓ ALLOWED" : "! DENIED"}
+
+Your permissions: ${context.session.permissions.join(", ")}
+Your role: ${context.session.role}`;
+  },
+  name: "check-permissions",
+  parameters: z.object({
+    operation: z.string().describe("Operation to check permission for"),
+  }),
+});
+
+// Resource that uses session context
+server.addResource({
+  description: "Get detailed information about the current authenticated user",
+  load: async (auth) => {
+    if (!auth) {
+      return {
+        text: JSON.stringify(
+          {
+            authenticated: false,
+            error: "No authentication context available",
+          },
+
+          null,
+          2,
+        ),
+      };
+    }
+
+    return {
+      text: JSON.stringify(
+        {
+          authenticated: true,
+          user: {
+            authenticatedAt: auth.authenticatedAt,
+            id: auth.userId,
+            permissions: auth.permissions,
+            role: auth.role,
+            username: auth.username,
+          },
+        },
+
+        null,
+        2,
+      ),
+    };
+  },
+  mimeType: "application/json",
+  name: "Current User Information",
+  uri: "session://current-user",
+});
+
+// Prompt that uses session context
+server.addPrompt({
+  arguments: [
+    {
+      description: "Greeting style (formal, casual, friendly)",
+      name: "style",
+      required: false,
+    },
+  ],
+  description: "Generate a personalized greeting based on the current user",
+  load: async (args, auth) => {
+    const style = args.style || "friendly";
+
+    if (!auth) {
+      return "Hello! I don't have access to your session information.";
+    }
+
+    const greetings = {
+      casual: `Hey ${auth.username}! Nice to see you again.`,
+      formal: `Good day, ${auth.username}. You are logged in with ${auth.role} privileges.`,
+      friendly: `Hello ${auth.username}! 😊 You're logged in as a ${auth.role}. How can I help you today?`,
+    };
+
+    return greetings[style as keyof typeof greetings] || greetings.friendly;
+  },
+  name: "personalized-greeting",
+});
+
+// Start the server
+if (process.argv.includes("--http-stream")) {
+  const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
+
+  server.start({
+    httpStream: { port: PORT },
+    transportType: "httpStream",
+  });
+
+  console.log(`
+🚀 Session Context Demo server running on HTTP Stream!
+
+Try these endpoints:
+- MCP: http://localhost:${PORT}/mcp
+- Health: http://localhost:${PORT}/health
+
+Test with curl:
+curl -H "Authorization: Bearer admin-token" \\
+     -H "Content-Type: application/json" \\
+     -d '{"method":"tools/call","params":{"name":"whoami","arguments":{}}}' \\
+     http://localhost:${PORT}/mcp
+`);
+} else {
+  server.start({ transportType: "stdio" });
+
+  console.log(`
+🚀 Session Context Demo server started with stdio transport!
+
+Environment variables for authentication:
+- USER_ID=${process.env.USER_ID || "(not set - will use 'default-user')"}
+- USERNAME=${process.env.USERNAME || "(not set - will use 'Anonymous')"}  
+- USER_ROLE=${process.env.USER_ROLE || "(not set - will use 'guest')"}
+
+To test with different user roles:
+USER_ID=admin001 USERNAME="John Admin" USER_ROLE=admin npx coolors-mcp dev src/examples/session-context.ts
+
+Available tools:
+- whoami: Get current user info
+- admin-operation: Test admin permissions  
+- check-permissions: Check specific permissions
+
+Available resources:
+- session://current-user: Current user JSON data
+
+Available prompts:
+- personalized-greeting: Get a personalized greeting
+`);
+}