design-constraint-validator 2.0.1 → 2.1.0

package/mcp/tools.ts

@@ -0,0 +1,254 @@
+import fs from 'node:fs';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { z } from 'zod';
+
+import { suggestIds } from '../core/cli-format.js';
+import { flattenTokens, type TokenNode } from '../core/flatten.js';
+import { explain, type WhyReport } from '../core/why.js';
+import { validate, type ValidateResult } from '../cli/validate-api.js';
+import type { DcvConfig } from '../cli/types.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import type { JsonObject, ValidateToolInput, WhyToolInput, GraphToolInput } from './contracts.js';
+import { graphInputShape, validateInputShape, whyInputShape } from './contracts.js';
+
+export type DcvMcpToolName = 'validate' | 'why' | 'graph';
+
+export interface ToolFailure {
+  ok: false;
+  tool: DcvMcpToolName;
+  error: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+export type ToolResponse<T extends { ok: boolean } & object> = ({ tool: DcvMcpToolName } & T) | ToolFailure;
+
+export class ToolExecutionError extends Error {
+  readonly code: string;
+  readonly details?: Record<string, unknown>;
+
+  constructor(code: string, message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export interface GraphToolResult {
+  ok: true;
+  nodes: string[];
+  edges: Array<[string, string]>;
+  meta: {
+    nodeCount: number;
+    edgeCount: number;
+  };
+}
+
+export type WhyToolResult = { ok: true } & WhyReport;
+
+interface TokenInput {
+  tokens?: JsonObject;
+  tokensPath?: string;
+  constraints?: JsonObject;
+  configPath?: string;
+  constraintsDir?: string;
+  breakpoint?: Breakpoint;
+}
+
+interface ToolDefinition<TInput, TResult extends { ok: boolean } & object> {
+  name: DcvMcpToolName;
+  description: string;
+  inputSchema: Record<string, z.ZodTypeAny>;
+  handler: (input: TInput) => Promise<ToolResponse<TResult>> | ToolResponse<TResult>;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'Unknown tool failure';
+}
+
+function toFailure(tool: DcvMcpToolName, error: unknown): ToolFailure {
+  if (error instanceof ToolExecutionError) {
+    return {
+      ok: false,
+      tool,
+      error: {
+        code: error.code,
+        message: error.message,
+        ...(error.details ? { details: error.details } : {}),
+      },
+    };
+  }
+
+  return {
+    ok: false,
+    tool,
+    error: {
+      code: 'tool_execution_failed',
+      message: errorMessage(error),
+    },
+  };
+}
+
+async function executeTool<T extends { ok: boolean } & object>(
+  tool: DcvMcpToolName,
+  fn: () => Promise<T> | T,
+): Promise<ToolResponse<T>> {
+  try {
+    return {
+      tool,
+      ...(await fn()),
+    };
+  } catch (error) {
+    return toFailure(tool, error);
+  }
+}
+
+function isToolFailure(result: ToolResponse<{ ok: boolean }>): result is ToolFailure {
+  return result.ok === false && 'error' in result;
+}
+
+function responseToContent(result: ToolResponse<{ ok: boolean }>): string {
+  return JSON.stringify(result, null, 2);
+}
+
+function parseJsonFile(filePath: string): unknown {
+  if (!fs.existsSync(filePath)) {
+    throw new ToolExecutionError('tokens_not_found', `Tokens file not found: ${filePath}`);
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new ToolExecutionError('invalid_tokens', `Tokens file is not valid JSON: ${filePath}`, {
+      cause: errorMessage(error),
+    });
+  }
+}
+
+function asJsonObject(value: unknown, label: string): JsonObject {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as JsonObject;
+  }
+
+  throw new ToolExecutionError('invalid_input', `${label} must be a JSON object.`);
+}
+
+function resolveTokens(input: TokenInput): TokenNode {
+  if (input.tokens !== undefined) {
+    return input.tokens as unknown as TokenNode;
+  }
+
+  if (input.tokensPath !== undefined) {
+    return asJsonObject(parseJsonFile(input.tokensPath), 'tokensPath contents') as unknown as TokenNode;
+  }
+
+  throw new ToolExecutionError('invalid_input', 'Provide either tokens or tokensPath.');
+}
+
+function constraints(input: TokenInput): DcvConfig['constraints'] | undefined {
+  return input.constraints as DcvConfig['constraints'] | undefined;
+}
+
+export async function validateTool(input: ValidateToolInput): Promise<ToolResponse<ValidateResult>> {
+  return executeTool('validate', () => {
+    if (input.tokens === undefined && input.tokensPath === undefined) {
+      throw new ToolExecutionError('invalid_input', 'Provide either tokens or tokensPath.');
+    }
+
+    return validate({
+      ...(input.tokens !== undefined ? { tokens: input.tokens as unknown as TokenNode } : {}),
+      ...(input.tokens === undefined && input.tokensPath !== undefined ? { tokensPath: input.tokensPath } : {}),
+      ...(input.constraints !== undefined ? { constraints: constraints(input) } : {}),
+      ...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
+      ...(input.constraintsDir !== undefined ? { constraintsDir: input.constraintsDir } : {}),
+      ...(input.breakpoint !== undefined ? { breakpoint: input.breakpoint } : {}),
+    });
+  });
+}
+
+export async function whyTool(input: WhyToolInput): Promise<ToolResponse<WhyToolResult>> {
+  return executeTool('why', () => {
+    const { flat, edges } = flattenTokens(resolveTokens(input));
+    if (!Object.prototype.hasOwnProperty.call(flat, input.tokenId)) {
+      throw new ToolExecutionError('unknown_token', `Unknown token id: ${input.tokenId}`, {
+        tokenId: input.tokenId,
+        suggestions: suggestIds(input.tokenId, Object.keys(flat)).map((suggestion) => suggestion.id),
+      });
+    }
+
+    return {
+      ok: true as const,
+      ...explain(input.tokenId, flat, edges),
+    };
+  });
+}
+
+export async function graphTool(input: GraphToolInput): Promise<ToolResponse<GraphToolResult>> {
+  return executeTool('graph', () => {
+    const { flat, edges } = flattenTokens(resolveTokens(input));
+    const nodes = Object.keys(flat).sort();
+
+    return {
+      ok: true as const,
+      nodes,
+      edges,
+      meta: {
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+      },
+    };
+  });
+}
+
+export const dcvMcpTools: Array<
+  | ToolDefinition<ValidateToolInput, ValidateResult>
+  | ToolDefinition<WhyToolInput, WhyToolResult>
+  | ToolDefinition<GraphToolInput, GraphToolResult>
+> = [
+  {
+    name: 'validate',
+    description: 'Validate DTCG-style design tokens against DCV constraints and return structured violations.',
+    inputSchema: validateInputShape,
+    handler: validateTool,
+  },
+  {
+    name: 'why',
+    description: 'Explain token provenance, aliases, immediate dependencies, dependents, and alias chain.',
+    inputSchema: whyInputShape,
+    handler: whyTool,
+  },
+  {
+    name: 'graph',
+    description: 'Return the token dependency graph as nodes and directed edges.',
+    inputSchema: graphInputShape,
+    handler: graphTool,
+  },
+];
+
+export function registerDcvMcpTools(server: McpServer): void {
+  for (const tool of dcvMcpTools) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      },
+      async (input): Promise<CallToolResult> => {
+        const result = await tool.handler(input as never);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: responseToContent(result as ToolResponse<{ ok: boolean }>),
+            },
+          ],
+          structuredContent: result as unknown as Record<string, unknown>,
+          ...(isToolFailure(result as ToolResponse<{ ok: boolean }>) ? { isError: true } : {}),
+        };
+      },
+    );
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-constraint-validator",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Mathematical constraint validator for design systems — ensuring consistency, accessibility, and logical coherence",
   "type": "module",
   "engines": {
@@ -14,30 +14,42 @@
       "import": "./core/index.js"
     },
     "./core/*": "./core/*",
-    "./cli/*": "./cli/*"
+    "./cli/*": "./cli/*",
+    "./mcp": {
+      "types": "./mcp/index.d.ts",
+      "import": "./mcp/index.js"
+    },
+    "./mcp/*": "./mcp/*"
   },
   "bin": {
     "dcv": "./cli/index.js",
-    "design-constraint-validator": "./cli/index.js"
+    "design-constraint-validator": "./cli/index.js",
+    "dcv-mcp": "./mcp/index.js"
   },
+  "mcpName": "io.github.cseperkepapp/design-constraint-validator",
   "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --exclude \"**/*.test.js\"",
+    "test:watch": "vitest --exclude \"**/*.test.js\"",
     "typecheck": "tsc --noEmit",
+    "workflow:typecheck": "tsc -p tsconfig.workflow-automation.json --noEmit",
+    "validate-headers": "tsx scripts/validate-headers.ts",
+    "workflow:test": "vitest run src/__tests__/task-workflow-integrity.test.ts src/__tests__/sync-task-index.test.ts",
+    "task:sync": "tsx scripts/sync-task-index.ts",
+    "rename-done-tasks": "tsx scripts/rename-done-tasks.ts",
     "build": "tsc",
     "lint": "eslint . --ext .js,.ts,.mjs,.cjs",
     "format": "prettier -w .",
-    "check": "npm run typecheck && npm run lint && npm test",
-    "prepublishOnly": "npm run check && npm run build",
+    "check": "npm run typecheck && npm run lint && npm run build && npm test",
+    "prepublishOnly": "npm run check",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
     "release:notes": "npm run changelog && git add CHANGELOG.md && git commit -m \"docs(changelog): update\"",
-    "release:patch": "npm version patch && git push && git push --tags && echo '\n⚠️  Now run: npm publish'",
-    "release:minor": "npm version minor && git push && git push --tags && echo '\n⚠️  Now run: npm publish'",
-    "release:major": "npm version major && git push && git push --tags && echo '\n⚠️  Now run: npm publish'",
-    "demo": "cd ../designLab-DEMO && npm run dev",
-    "demo:build": "cd ../designLab-DEMO && npm run build",
-    "demo:v2": "cd designLab-v2 && npm run dev",
-    "demo:v2:build": "cd designLab-v2 && npm run build"
+    "release:patch": "npm version patch && git push && git push --tags && echo '\n✅ Tag pushed. CI (.github/workflows/publish.yml) will build, publish, and verify the version on npm — no manual npm publish needed. Watch the Actions run.'",
+    "release:minor": "npm version minor && git push && git push --tags && echo '\n✅ Tag pushed. CI (.github/workflows/publish.yml) will build, publish, and verify the version on npm — no manual npm publish needed. Watch the Actions run.'",
+    "release:major": "npm version major && git push && git push --tags && echo '\n✅ Tag pushed. CI (.github/workflows/publish.yml) will build, publish, and verify the version on npm — no manual npm publish needed. Watch the Actions run.'",
+    "demo": "node -e \"const fs=require('node:fs');const cp=require('node:child_process');const dir='../designLab-DEMO';if(!fs.existsSync(dir)){console.error('Demo repo not found at ../designLab-DEMO. Clone it next to this repo to run npm run demo.');process.exit(1)}const r=cp.spawnSync('npm',['run','dev'],{cwd:dir,stdio:'inherit',shell:true});process.exit(r.status===null?1:r.status)\"",
+    "demo:build": "node -e \"const fs=require('node:fs');const cp=require('node:child_process');const dir='../designLab-DEMO';if(!fs.existsSync(dir)){console.error('Demo repo not found at ../designLab-DEMO. Clone it next to this repo to run npm run demo:build.');process.exit(1)}const r=cp.spawnSync('npm',['run','build'],{cwd:dir,stdio:'inherit',shell:true});process.exit(r.status===null?1:r.status)\"",
+    "demo:v2": "node -e \"const fs=require('node:fs');const cp=require('node:child_process');const dir='designLab-v2';if(!fs.existsSync(dir)){console.error('Demo repo not found at designLab-v2. Add it inside this repo to run npm run demo:v2.');process.exit(1)}const r=cp.spawnSync('npm',['run','dev'],{cwd:dir,stdio:'inherit',shell:true});process.exit(r.status===null?1:r.status)\"",
+    "demo:v2:build": "node -e \"const fs=require('node:fs');const cp=require('node:child_process');const dir='designLab-v2';if(!fs.existsSync(dir)){console.error('Demo repo not found at designLab-v2. Add it inside this repo to run npm run demo:v2:build.');process.exit(1)}const r=cp.spawnSync('npm',['run','build'],{cwd:dir,stdio:'inherit',shell:true});process.exit(r.status===null?1:r.status)\""
   },
   "keywords": [
     "design-constraints",
@@ -67,29 +79,32 @@
     "access": "public"
   },
   "dependencies": {
-    "fast-glob": "^3.3.2",
-    "yargs": "^17.0.0",
-    "zod": "^3.0.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yargs": "^17.7.2",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/yargs": "^17.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
+    "@types/node": "^22.19.21",
+    "@types/yargs": "^17.0.35",
+    "@typescript-eslint/eslint-plugin": "^8.61.0",
+    "@typescript-eslint/parser": "^8.61.0",
     "conventional-changelog-cli": "^2.2.2",
-    "eslint": "^9.0.0",
+    "eslint": "^9.39.4",
     "eslint-config-prettier": "^9.0.0",
+    "glob": "^11.1.0",
     "pdf-parse": "^2.4.5",
-    "prettier": "^3.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^3.0.0"
+    "prettier": "^3.8.4",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
   },
   "files": [
     "cli/",
     "core/",
+    "mcp/",
     "adapters/",
     "themes/",
+    "server.json",
     "LICENSE",
     "README.md"
   ]

package/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.cseperkepapp/design-constraint-validator",
+  "title": "Design Constraint Validator",
+  "description": "Validate design tokens for accessibility, scales, and design-system constraint consistency.",
+  "version": "2.1.0",
+  "repository": {
+    "url": "https://github.com/CseperkePapp/design-constraint-validator",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "design-constraint-validator",
+      "version": "2.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/cli/constraints-loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constraints-loader.d.ts","sourceRoot":"","sources":["constraints-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAkDtF"}

package/cli/engine-helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"engine-helpers.d.ts","sourceRoot":"","sources":["engine-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI3C,OAAO,EAA8B,wBAAwB,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC/G,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgE5C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,GAAE,SAAc,GAAG,MAAM,CAQlF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAgBnH;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/core/cross-axis-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cross-axis-config.d.ts","sourceRoot":"","sources":["cross-axis-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,0CA2HnD"}