@stackwright-pro/mcp 0.2.0-alpha.68 → 0.2.0-alpha.71

package/dist/server.mjs

@@ -3029,6 +3029,13 @@ var PHASE_ARTIFACT_SCHEMA = {
           mutationType: null
         }
       ],
+      skipped: [
+        {
+          spec: "ais-message-models.yaml",
+          format: "asyncapi",
+          reason: "AsyncAPI spec \u2014 WebSocket/event integration required (no REST endpoints)"
+        }
+      ],
       auth: { type: "bearer", header: "Authorization", envVar: "API_TOKEN" },
       baseUrl: "https://api.example.mil/v2",
       specPath: "./specs/api.yaml"
@@ -4001,6 +4008,91 @@ ${auditBlock}
 ${routesBlock}
 });
 
+${configBlock}
+`;
+}
+function generateProxyContent(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
+  const rbacBlock = `  rbac: {
+    roles: ${JSON.stringify(roles)},
+    defaultRole: '${defaultRole}',
+    hierarchy: ${JSON.stringify(hierarchy, null, 4)},
+  },`;
+  const auditBlock = `  audit: {
+    enabled: ${auditEnabled},
+    retentionDays: ${auditRetentionDays},
+  },`;
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const configBlock = `export const config = {
+  matcher: ${JSON.stringify(protectedRoutes)},
+};`;
+  if (method === "cac") {
+    const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
+    const edipiLookup = params.cacEdipiLookup ?? "./config/edipi-lookup.json";
+    const ocspEndpoint = params.cacOcspEndpoint ?? "https://ocsp.disa.mil";
+    const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
+    return `// proxy.ts \u2014 generated by @stackwright-pro/auth (Next.js >=16)
+//   SECURITY REVIEW REQUIRED \u2014 CAC/PKI certificate validation
+// DoD security officer review required before production deployment.
+// Verify: CA bundle completeness, EDIPI lookup endpoint, OCSP accessibility.
+import { createAuthProxy } from '@stackwright-pro/auth-nextjs';
+
+export const proxy = createAuthProxy({
+  method: 'cac',
+  cac: {
+    caBundle: process.env.CAC_CA_BUNDLE ?? '${caBundle}',
+    edipiLookup: '${edipiLookup}',
+    ocspEndpoint: process.env.CAC_OCSP_ENDPOINT ?? '${ocspEndpoint}',
+    certHeader: '${certHeader}',
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+  }
+  if (method === "oidc") {
+    const scopes2 = params.oidcScopes ?? "openid profile email";
+    const roleClaim = params.oidcRoleClaim ?? "roles";
+    return `// proxy.ts \u2014 generated by @stackwright-pro/auth (Next.js >=16)
+import { createAuthProxy } from '@stackwright-pro/auth-nextjs';
+
+export const proxy = createAuthProxy({
+  method: 'oidc',
+  oidc: {
+    discoveryUrl: process.env.OIDC_DISCOVERY_URL!,
+    clientId: process.env.OIDC_CLIENT_ID!,
+    clientSecret: process.env.OIDC_CLIENT_SECRET!,
+    scopes: '${scopes2}',
+    roleClaim: '${roleClaim}',
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+  }
+  const scopes = params.oauth2Scopes ?? "read write";
+  return `// proxy.ts \u2014 generated by @stackwright-pro/auth (Next.js >=16)
+import { createAuthProxy } from '@stackwright-pro/auth-nextjs';
+
+export const proxy = createAuthProxy({
+  method: 'oauth2',
+  oauth2: {
+    authorizationUrl: process.env.OAUTH2_AUTH_URL!,
+    tokenUrl: process.env.OAUTH2_TOKEN_URL!,
+    clientId: process.env.OAUTH2_CLIENT_ID!,
+    clientSecret: process.env.OAUTH2_CLIENT_SECRET!,
+    scopes: '${scopes}',
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
 ${configBlock}
 `;
 }
@@ -4030,7 +4122,7 @@ OAUTH2_CLIENT_ID=your-client-id
 OAUTH2_CLIENT_SECRET=your-client-secret
 `;
 }
-function generateYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
+function generateYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes, useProxy) {
   const rbacSection = `  rbac:
     roles:
 ${rolesToYaml(roles, "      ")}
@@ -4053,7 +4145,7 @@ ${routesToYaml(protectedRoutes, "    ", defaultRole)}`.replace(/\n\s+,/g, "");
     const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
     return `auth:
   method: cac
-${providerLine}  middleware: ./middleware.ts
+${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
   cac:
     caBundle: \${CAC_CA_BUNDLE}
     edipiLookup: ${edipiLookup}
@@ -4070,7 +4162,7 @@ ${auditSection}
     const roleClaim = params.oidcRoleClaim ?? "roles";
     return `auth:
   method: oidc
-${providerLine}  middleware: ./middleware.ts
+${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
   oidc:
     discoveryUrl: \${OIDC_DISCOVERY_URL}
     clientId: \${OIDC_CLIENT_ID}
@@ -4086,7 +4178,7 @@ ${auditSection}
   const scopes = params.oauth2Scopes ?? "read write";
   return `auth:
   method: oauth2
-${providerLine}  middleware: ./middleware.ts
+${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
   oauth2:
     authorizationUrl: \${OAUTH2_AUTH_URL}
     tokenUrl: \${OAUTH2_TOKEN_URL}
@@ -4188,7 +4280,96 @@ ${routesBlock}
 ${configBlock}
 `;
 }
-function generateDevOnlyYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
+function generateDevOnlyProxyContent(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
+  const rbacBlock = `  rbac: {
+    roles: ${JSON.stringify(roles)},
+    defaultRole: '${defaultRole}',
+    hierarchy: ${JSON.stringify(hierarchy, null, 4)},
+  },`;
+  const auditBlock = `  audit: {
+    enabled: ${auditEnabled},
+    retentionDays: ${auditRetentionDays},
+  },`;
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const configBlock = `export const config = {
+  matcher: ${JSON.stringify(protectedRoutes)},
+};`;
+  const devHeader = [
+    "// proxy.ts -- generated by @stackwright-pro/auth (Next.js >=16, dev-only mock)",
+    "//   DEV ONLY -- uses mock authentication from lib/mock-auth.ts",
+    "// Do NOT deploy to production.",
+    "import { createAuthProxy } from '@stackwright-pro/auth-nextjs';",
+    "import { mockAuthProvider } from './lib/mock-auth';"
+  ].join("\n");
+  if (method === "cac") {
+    const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
+    const edipiLookup = params.cacEdipiLookup ?? "./config/edipi-lookup.json";
+    const ocspEndpoint = params.cacOcspEndpoint ?? "https://ocsp.disa.mil";
+    const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
+    return `${devHeader}
+
+export const proxy = createAuthProxy({
+  method: 'cac',
+  cac: {
+    caBundle: '${caBundle}',
+    edipiLookup: '${edipiLookup}',
+    ocspEndpoint: '${ocspEndpoint}',
+    certHeader: '${certHeader}',
+    provider: mockAuthProvider,
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+  }
+  if (method === "oidc") {
+    const scopes2 = params.oidcScopes ?? "openid profile email";
+    const roleClaim = params.oidcRoleClaim ?? "roles";
+    return `${devHeader}
+
+export const proxy = createAuthProxy({
+  method: 'oidc',
+  oidc: {
+    discoveryUrl: 'https://dev-mock-oidc/.well-known/openid-configuration',
+    clientId: 'dev-mock-client',
+    clientSecret: 'dev-mock-secret',
+    scopes: '${scopes2}',
+    roleClaim: '${roleClaim}',
+    provider: mockAuthProvider,
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+  }
+  const scopes = params.oauth2Scopes ?? "read write";
+  return `${devHeader}
+
+export const proxy = createAuthProxy({
+  method: 'oauth2',
+  oauth2: {
+    authorizationUrl: 'https://dev-mock-oauth2/authorize',
+    tokenUrl: 'https://dev-mock-oauth2/token',
+    clientId: 'dev-mock-client',
+    clientSecret: 'dev-mock-secret',
+    scopes: '${scopes}',
+    provider: mockAuthProvider,
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+}
+function generateDevOnlyYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes, useProxy) {
   const rbacSection = `  rbac:
     roles:
 ${rolesToYaml(roles, "      ")}
@@ -4210,7 +4391,7 @@ ${hierarchyToYaml(hierarchy, "      ")}`;
     return `auth:
   method: cac
   devOnly: true
-${providerLine}  middleware: ./middleware.ts
+${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
   cac:
     caBundle: ${caBundle}
     edipiLookup: ${edipiLookup}
@@ -4228,7 +4409,7 @@ ${auditSection}
     return `auth:
   method: oidc
   devOnly: true
-${providerLine}  middleware: ./middleware.ts
+${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
   oidc:
     discoveryUrl: https://dev-mock-oidc/.well-known/openid-configuration
     clientId: dev-mock-client
@@ -4245,7 +4426,7 @@ ${auditSection}
   return `auth:
   method: oauth2
   devOnly: true
-${providerLine}  middleware: ./middleware.ts
+${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
   oauth2:
     authorizationUrl: https://dev-mock-oauth2/authorize
     tokenUrl: https://dev-mock-oauth2/token
@@ -4333,6 +4514,8 @@ async function configureAuthHandler(params, cwd) {
   const roles = rbacRoles;
   const defaultRole = params.rbacDefaultRole ?? roles[roles.length - 1];
   const hierarchy = buildHierarchy(roles);
+  const useProxy = (params.nextMajorVersion ?? 0) >= 16;
+  const conventionFile = useProxy ? "proxy.ts" : "middleware.ts";
   if (method === "none") {
     return {
       content: [
@@ -4354,7 +4537,25 @@ async function configureAuthHandler(params, cwd) {
   }
   const filesWritten = [];
   try {
-    const middlewareContent = devOnly ? generateDevOnlyMiddlewareContent(
+    const authFileContent = devOnly ? useProxy ? generateDevOnlyProxyContent(
+      method,
+      params,
+      roles,
+      defaultRole,
+      hierarchy,
+      auditEnabled,
+      auditRetentionDays,
+      protectedRoutes
+    ) : generateDevOnlyMiddlewareContent(
+      method,
+      params,
+      roles,
+      defaultRole,
+      hierarchy,
+      auditEnabled,
+      auditRetentionDays,
+      protectedRoutes
+    ) : useProxy ? generateProxyContent(
       method,
       params,
       roles,
@@ -4373,15 +4574,18 @@ async function configureAuthHandler(params, cwd) {
       auditRetentionDays,
       protectedRoutes
     );
-    writeFileSync6(join6(cwd, "middleware.ts"), middlewareContent, "utf8");
-    filesWritten.push("middleware.ts");
+    writeFileSync6(join6(cwd, conventionFile), authFileContent, "utf8");
+    filesWritten.push(conventionFile);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify({ success: false, error: `Failed writing middleware.ts: ${msg}` })
+          text: JSON.stringify({
+            success: false,
+            error: `Failed writing ${conventionFile}: ${msg}`
+          })
         }
       ],
       isError: true
@@ -4466,7 +4670,8 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes
+      protectedRoutes,
+      useProxy
     ) : generateYamlBlock(
       method,
       params,
@@ -4475,7 +4680,8 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes
+      protectedRoutes,
+      useProxy
     );
     const ymlPath = join6(cwd, "stackwright.yml");
     if (!existsSync7(ymlPath)) {
@@ -4510,6 +4716,8 @@ async function configureAuthHandler(params, cwd) {
           rbacDefaultRole: defaultRole,
           protectedRoutesCount: protectedRoutes.length,
           filesWritten,
+          convention: useProxy ? "proxy" : "middleware",
+          nextMajorVersion: params.nextMajorVersion ?? null,
           securityWarning,
           ...devOnly ? {
             devScripts: {
@@ -4565,7 +4773,8 @@ function registerAuthTools(server2) {
       // Injection for tests
       _cwd: z13.string().optional(),
       devOnly: boolCoerce(z13.boolean().optional()),
-      mockUsers: jsonCoerce(z13.array(z13.object({ name: z13.string(), email: z13.string() })).optional())
+      mockUsers: jsonCoerce(z13.array(z13.object({ name: z13.string(), email: z13.string() })).optional()),
+      nextMajorVersion: numCoerce(z13.number().int().positive().optional())
     },
     async (params) => {
       const cwd = params._cwd ?? process.cwd();
@@ -4581,11 +4790,11 @@ import { join as join7, basename } from "path";
 var _checksums = /* @__PURE__ */ new Map([
   [
     "stackwright-pro-api-otter.json",
-    "9fbaed0ce6116b82d0289f24432037d04637c89b8e73062ed946e5d49b294734"
+    "c21f127b9bed477b1d7b66949926e00e1b93de081e792293ebfffc88b70d9424"
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "c3be215f05cc48ec51ed75541184b89a8ac123463b80fe02f2adb6c1b5163853"
+    "6d4d4d50f52be84a796c2a43ed997f00b41b42ed8c5f046e1defb2e423933588"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
@@ -4605,7 +4814,7 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "5f18e37ee3f2064c62a2d01dfc541285f27e5762d0b1011e2a37a48af96c74c8"
+    "e563a99d647fcf95401508f15f10e032fb14e826577bc6bcff5960bf2981d58d"
   ],
   [
     "stackwright-pro-geo-otter.json",
@@ -4613,15 +4822,15 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-page-otter.json",
-    "1dcdf866be76d18f3aa2a9e56b8bf57a3d43477b43c410eb6d1feac0e7683658"
+    "cdd878857c1d809c60263693ab0c6cbb45087fd9c3eeda5b4628bd7026d2bded"
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "72a52901b4781c9f0be97024ba6e19415cdfbd92369d9274aa3abe7efd208bc8"
+    "e5f88d054dd536646f48e5d47cbd64f825f493100002309b90c912fa69ef279e"
   ],
   [
     "stackwright-pro-theme-otter.json",
-    "e8530a1146abc57eb31d2f036ba057d5eae7d4a2d9dca00e415d1c352ef4c5b5"
+    "532d9ca7db6911a09ce5029a8c74c89360bdf6cb8ede8c2636866b509cbe06f9"
   ],
   [
     "stackwright-pro-workflow-otter.json",
@@ -5524,6 +5733,245 @@ function registerScaffoldCleanupTools(server2) {
   );
 }
 
+// src/tools/contrast.ts
+import { z as z16 } from "zod";
+function linearizeChannel(c255) {
+  const c = c255 / 255;
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+function relativeLuminance(r, g, b) {
+  return 0.2126 * linearizeChannel(r) + 0.7152 * linearizeChannel(g) + 0.0722 * linearizeChannel(b);
+}
+function contrastRatioFromLuminance(l1, l2) {
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function parseHex(hex) {
+  const clean = hex.replace("#", "").trim().toLowerCase();
+  if (clean.length === 3) {
+    const r = parseInt(clean.charAt(0) + clean.charAt(0), 16);
+    const g = parseInt(clean.charAt(1) + clean.charAt(1), 16);
+    const b = parseInt(clean.charAt(2) + clean.charAt(2), 16);
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return [r, g, b];
+  }
+  if (clean.length === 6) {
+    const r = parseInt(clean.slice(0, 2), 16);
+    const g = parseInt(clean.slice(2, 4), 16);
+    const b = parseInt(clean.slice(4, 6), 16);
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return [r, g, b];
+  }
+  return null;
+}
+function hslToRgb(h, s, l) {
+  const hn = h / 360;
+  const sn = s / 100;
+  const ln = l / 100;
+  const hue2rgb = (p, q, t) => {
+    let tt = t;
+    if (tt < 0) tt += 1;
+    if (tt > 1) tt -= 1;
+    if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+    if (tt < 1 / 2) return q;
+    if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+    return p;
+  };
+  let r, g, b;
+  if (sn === 0) {
+    r = g = b = ln;
+  } else {
+    const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+    const p = 2 * ln - q;
+    r = hue2rgb(p, q, hn + 1 / 3);
+    g = hue2rgb(p, q, hn);
+    b = hue2rgb(p, q, hn - 1 / 3);
+  }
+  return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+}
+function parseHsl(hsl) {
+  let str = hsl.replace(/^hsl\s*\(\s*/i, "").replace(/\s*\)$/, "").trim();
+  str = str.replace(/%/g, "");
+  const parts = str.split(/[\s,]+/).filter(Boolean);
+  if (parts.length !== 3) return null;
+  const h = parseFloat(parts[0]);
+  const s = parseFloat(parts[1]);
+  const l = parseFloat(parts[2]);
+  if (isNaN(h) || isNaN(s) || isNaN(l)) return null;
+  return hslToRgb(h, s, l);
+}
+function parseColor(color) {
+  const trimmed = color.trim();
+  if (trimmed.startsWith("#")) return parseHex(trimmed);
+  if (/^hsl\s*\(/i.test(trimmed)) return parseHsl(trimmed);
+  if (/^\d[\d.]*[\s,]+\d[\d.]*%?[\s,]+\d[\d.]*%?$/.test(trimmed)) return parseHsl(trimmed);
+  return null;
+}
+function rgbToHex(r, g, b) {
+  return "#" + [r, g, b].map(
+    (c) => Math.max(0, Math.min(255, Math.round(c))).toString(16).padStart(2, "0")
+  ).join("");
+}
+function handleCheckContrast(fg, bg) {
+  const fgRgb = parseColor(fg);
+  const bgRgb = parseColor(bg);
+  if (!fgRgb) throw new Error(`Cannot parse foreground color: "${fg}"`);
+  if (!bgRgb) throw new Error(`Cannot parse background color: "${bg}"`);
+  const fgL = relativeLuminance(...fgRgb);
+  const bgL = relativeLuminance(...bgRgb);
+  const ratio = parseFloat(contrastRatioFromLuminance(fgL, bgL).toFixed(2));
+  return {
+    fgHex: rgbToHex(...fgRgb),
+    bgHex: rgbToHex(...bgRgb),
+    ratio,
+    aa: ratio >= 4.5,
+    aaLarge: ratio >= 3,
+    aaa: ratio >= 7,
+    aaaLarge: ratio >= 4.5
+  };
+}
+function handleDeriveAccessiblePalette(seed, targetRatio) {
+  const seedRgb = parseColor(seed);
+  if (!seedRgb) throw new Error(`Cannot parse seed color: "${seed}"`);
+  const seedHex = rgbToHex(...seedRgb);
+  const seedL = relativeLuminance(...seedRgb);
+  const whiteRatio = parseFloat(contrastRatioFromLuminance(1, seedL).toFixed(2));
+  const blackRatio = parseFloat(contrastRatioFromLuminance(0, seedL).toFixed(2));
+  const whiteWorks = whiteRatio >= targetRatio;
+  const blackWorks = blackRatio >= targetRatio;
+  let strategy;
+  let foreground;
+  let ratio;
+  let alternativeForeground;
+  let alternativeRatio;
+  if (blackWorks && whiteWorks) {
+    if (blackRatio >= whiteRatio) {
+      strategy = "black";
+      foreground = "#000000";
+      ratio = blackRatio;
+      alternativeForeground = "#ffffff";
+      alternativeRatio = whiteRatio;
+    } else {
+      strategy = "white";
+      foreground = "#ffffff";
+      ratio = whiteRatio;
+      alternativeForeground = "#000000";
+      alternativeRatio = blackRatio;
+    }
+  } else if (blackWorks) {
+    strategy = "black";
+    foreground = "#000000";
+    ratio = blackRatio;
+    alternativeForeground = "#ffffff";
+    alternativeRatio = whiteRatio;
+  } else if (whiteWorks) {
+    strategy = "white";
+    foreground = "#ffffff";
+    ratio = whiteRatio;
+    alternativeForeground = "#000000";
+    alternativeRatio = blackRatio;
+  } else {
+    strategy = "unachievable";
+    if (blackRatio >= whiteRatio) {
+      foreground = "#000000";
+      ratio = blackRatio;
+      alternativeForeground = "#ffffff";
+      alternativeRatio = whiteRatio;
+    } else {
+      foreground = "#ffffff";
+      ratio = whiteRatio;
+      alternativeForeground = "#000000";
+      alternativeRatio = blackRatio;
+    }
+  }
+  return {
+    seedHex,
+    foreground,
+    ratio,
+    aa: ratio >= 4.5,
+    aaLarge: ratio >= 3,
+    aaa: ratio >= 7,
+    meetsTarget: ratio >= targetRatio,
+    strategy,
+    alternativeForeground,
+    alternativeRatio
+  };
+}
+var PASS = "[PASS]";
+var FAIL = "[FAIL]";
+var mark = (ok) => ok ? PASS : FAIL;
+function registerContrastTools(server2) {
+  server2.tool(
+    "stackwright_pro_check_contrast",
+    'Compute the exact WCAG 2.1 contrast ratio between a foreground and background color. Returns the ratio and AA/AAA pass/fail flags. Use this to verify any foreground/background color pair before writing it to the token set. Accepts #RGB, #RRGGBB, hsl(...), or shadcn HSL format ("H S% L%").',
+    {
+      fg: z16.string().describe("Foreground (text) color \u2014 hex or HSL"),
+      bg: z16.string().describe("Background color \u2014 hex or HSL")
+    },
+    async ({ fg, bg }) => {
+      let result;
+      try {
+        result = handleCheckContrast(fg, bg);
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }]
+        };
+      }
+      const text = [
+        `WCAG 2.1 Contrast Check`,
+        ``,
+        `  Foreground : ${result.fgHex}`,
+        `  Background : ${result.bgHex}`,
+        `  Ratio      : ${result.ratio}:1`,
+        ``,
+        `  ${mark(result.aa)}  AA  \u2014 normal text  (\u22654.5:1)`,
+        `  ${mark(result.aaLarge)}  AA  \u2014 large text   (\u22653.0:1)`,
+        `  ${mark(result.aaa)}  AAA \u2014 normal text  (\u22657.0:1)`,
+        `  ${mark(result.aaaLarge)}  AAA \u2014 large text   (\u22654.5:1)`
+      ].join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_derive_accessible_palette",
+    'Given a seed color (treated as a background), derive the best accessible foreground (text) color that meets the target contrast ratio. Evaluates #ffffff and #000000 against the seed and picks whichever satisfies the target ratio with the highest contrast. Use this for every {name}-foreground token derivation instead of guessing white vs black. Accepts #RGB, #RRGGBB, hsl(...), or shadcn HSL format ("H S% L%").',
+    {
+      seed: z16.string().describe("Background (seed) color \u2014 hex or HSL"),
+      targetRatio: numCoerce(z16.number().default(4.5)).describe(
+        "Minimum required contrast ratio (default 4.5 for WCAG AA)"
+      )
+    },
+    async ({ seed, targetRatio }) => {
+      let result;
+      try {
+        result = handleDeriveAccessiblePalette(seed, targetRatio ?? 4.5);
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }]
+        };
+      }
+      const metLine = result.meetsTarget ? `${PASS} Meets target (${targetRatio}:1)` : `${FAIL} Target (${targetRatio}:1) UNACHIEVABLE with white or black \u2014 best available used`;
+      const altNote = result.alternativeRatio >= (targetRatio ?? 4.5) ? `also passes (${result.alternativeRatio}:1)` : `fails at ${result.alternativeRatio}:1`;
+      const text = [
+        `Accessible Palette Derivation`,
+        ``,
+        `  Background (seed) : ${result.seedHex}`,
+        `  Foreground        : ${result.foreground}  (${result.strategy})`,
+        `  Contrast ratio    : ${result.ratio}:1`,
+        `  ${metLine}`,
+        ``,
+        `  ${mark(result.aa)}  AA  \u2014 normal text  (\u22654.5:1)`,
+        `  ${mark(result.aaLarge)}  AA  \u2014 large text   (\u22653.0:1)`,
+        `  ${mark(result.aaa)}  AAA \u2014 normal text  (\u22657.0:1)`,
+        ``,
+        `  Alternative (${result.alternativeForeground}): ${altNote}`
+      ].join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
 // package.json
 var package_default = {
   dependencies: {
@@ -5547,7 +5995,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.68",
+  version: "0.2.0-alpha.71",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -5602,6 +6050,7 @@ registerArtifactSigningTools(server);
 registerDomainTools(server);
 registerTypeSchemasTool(server);
 registerScaffoldCleanupTools(server);
+registerContrastTools(server);
 async function main() {
   const transport = new StdioServerTransport();
   try {