@blue-patterns/mcp 0.0.0-stage → 0.7.18

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Blue-Patterns-UI Contributors
+Portions Copyright (c) 2026 Meta Platforms, Inc. (Astryx upstream foundation)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @blue-patterns/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deterministic Model Context Protocol (MCP) server exposing Blue-Patterns-UI contracts, validation, and component discovery to AI coding agents.
+
+## Features
+
+- **Component Search (`ds_search_components`):** Rapid semantic search across component contracts, visual variants, token slots, and accessibility roles.
+- **Contract Inspection (`ds_get_contract`):** Retrieve machine-readable `.doc.mjs` component specifications, prop schemas, and usage examples.
+- **JSX AST Validation (`ds_validate_jsx`):** Validate JSX source code against Blue-Patterns-UI invariants (zero raw hex colors, valid component imports, accessible props).
+- **Token Discovery (`ds_list_tokens`):** Query CSS custom property design tokens across colors, spacing, radii, typography, and spring motion curves.
+
+## Usage
+
+### Direct Execution
+
+```bash
+npx @blue-patterns/mcp
+# or
+pnpm dlx @blue-patterns/mcp
+```
+
+### In Agent / Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "blue-patterns": {
+      "command": "npx",
+      "args": ["-y", "@blue-patterns/mcp"]
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/bin/mcp-server.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { startMcpServer } from '../dist/server.js';
+
+startMcpServer();

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './tools/search.js';
+export * from './tools/contract.js';
+export * from './tools/validate.js';
+export * from './tools/swizzle.js';
+export { startMcpServer } from './server.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './tools/search.js';
+export * from './tools/contract.js';
+export * from './tools/validate.js';
+export * from './tools/swizzle.js';
+export { startMcpServer } from './server.js';

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): void;

package/dist/server.js

@@ -0,0 +1,142 @@
+import readline from 'node:readline';
+import { dsSearch } from './tools/search.js';
+import { dsContract } from './tools/contract.js';
+import { dsValidateJsx } from './tools/validate.js';
+import { dsSwizzle } from './tools/swizzle.js';
+export function startMcpServer() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    const tools = [
+        {
+            name: 'ds_search',
+            description: 'Ranked search across all 150+ components, hooks, motion primitives, and theme packs.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search term or component name' },
+                    category: { type: 'string', description: 'Optional category filter: Component, DataViz, Motion, Theme' },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'ds_contract',
+            description: 'Batch-returns typed props, variant enums, CSS token dependencies, and dense usage rules.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    componentNames: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of component names to inspect',
+                    },
+                },
+                required: ['componentNames'],
+            },
+        },
+        {
+            name: 'ds_validate_jsx',
+            description: 'Static AST validator checking for hallucinated components, invalid props, or raw hex colors.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tsxCode: { type: 'string', description: 'TSX / JSX source code to validate' },
+                },
+                required: ['tsxCode'],
+            },
+        },
+        {
+            name: 'ds_swizzle',
+            description: 'Eject component source, StyleX styles, and tests into a consumer local directory.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    componentName: { type: 'string', description: 'Component to swizzle/eject' },
+                    destinationPath: { type: 'string', description: 'Target destination directory' },
+                },
+                required: ['componentName', 'destinationPath'],
+            },
+        },
+    ];
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        try {
+            const request = JSON.parse(line);
+            const { id, method, params } = request;
+            if (method === 'initialize') {
+                const response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: '2024-11-05',
+                        serverInfo: {
+                            name: 'blue-patterns-mcp',
+                            version: '0.1.0',
+                        },
+                        capabilities: {
+                            tools: {},
+                        },
+                    },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+            else if (method === 'tools/list') {
+                const response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        tools,
+                    },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+            else if (method === 'tools/call') {
+                const toolName = params?.name;
+                const args = params?.arguments || {};
+                let resultData = null;
+                if (toolName === 'ds_search') {
+                    resultData = dsSearch(args.query || '', args.category);
+                }
+                else if (toolName === 'ds_contract') {
+                    resultData = dsContract(args.componentNames || []);
+                }
+                else if (toolName === 'ds_validate_jsx') {
+                    resultData = dsValidateJsx(args.tsxCode || '');
+                }
+                else if (toolName === 'ds_swizzle') {
+                    resultData = dsSwizzle(args.componentName || '', args.destinationPath || '');
+                }
+                else {
+                    throw new Error(`Unknown tool: ${toolName}`);
+                }
+                const response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(resultData, null, 2),
+                            },
+                        ],
+                    },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+        }
+        catch (err) {
+            const errorResponse = {
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: err.message,
+                },
+            };
+            process.stdout.write(JSON.stringify(errorResponse) + '\n');
+        }
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './tools/search.js';
+export * from './tools/contract.js';
+export * from './tools/validate.js';
+export * from './tools/swizzle.js';
+export { startMcpServer } from './server.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export * from './tools/search.js';
+export * from './tools/contract.js';
+export * from './tools/validate.js';
+export * from './tools/swizzle.js';
+export { startMcpServer } from './server.js';

package/dist/src/server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): void;

package/dist/src/server.js

@@ -0,0 +1,142 @@
+import readline from 'node:readline';
+import { dsSearch } from './tools/search.js';
+import { dsContract } from './tools/contract.js';
+import { dsValidateJsx } from './tools/validate.js';
+import { dsSwizzle } from './tools/swizzle.js';
+export function startMcpServer() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    const tools = [
+        {
+            name: 'ds_search',
+            description: 'Ranked search across all 150+ components, hooks, motion primitives, and theme packs.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search term or component name' },
+                    category: { type: 'string', description: 'Optional category filter: Component, DataViz, Motion, Theme' },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'ds_contract',
+            description: 'Batch-returns typed props, variant enums, CSS token dependencies, and dense usage rules.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    componentNames: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of component names to inspect',
+                    },
+                },
+                required: ['componentNames'],
+            },
+        },
+        {
+            name: 'ds_validate_jsx',
+            description: 'Static AST validator checking for hallucinated components, invalid props, or raw hex colors.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tsxCode: { type: 'string', description: 'TSX / JSX source code to validate' },
+                },
+                required: ['tsxCode'],
+            },
+        },
+        {
+            name: 'ds_swizzle',
+            description: 'Eject component source, StyleX styles, and tests into a consumer local directory.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    componentName: { type: 'string', description: 'Component to swizzle/eject' },
+                    destinationPath: { type: 'string', description: 'Target destination directory' },
+                },
+                required: ['componentName', 'destinationPath'],
+            },
+        },
+    ];
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        try {
+            const request = JSON.parse(line);
+            const { id, method, params } = request;
+            if (method === 'initialize') {
+                const response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: '2024-11-05',
+                        serverInfo: {
+                            name: 'blue-patterns-mcp',
+                            version: '0.1.0',
+                        },
+                        capabilities: {
+                            tools: {},
+                        },
+                    },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+            else if (method === 'tools/list') {
+                const response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        tools,
+                    },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+            else if (method === 'tools/call') {
+                const toolName = params?.name;
+                const args = params?.arguments || {};
+                let resultData = null;
+                if (toolName === 'ds_search') {
+                    resultData = dsSearch(args.query || '', args.category);
+                }
+                else if (toolName === 'ds_contract') {
+                    resultData = dsContract(args.componentNames || []);
+                }
+                else if (toolName === 'ds_validate_jsx') {
+                    resultData = dsValidateJsx(args.tsxCode || '');
+                }
+                else if (toolName === 'ds_swizzle') {
+                    resultData = dsSwizzle(args.componentName || '', args.destinationPath || '');
+                }
+                else {
+                    throw new Error(`Unknown tool: ${toolName}`);
+                }
+                const response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(resultData, null, 2),
+                            },
+                        ],
+                    },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+        }
+        catch (err) {
+            const errorResponse = {
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: err.message,
+                },
+            };
+            process.stdout.write(JSON.stringify(errorResponse) + '\n');
+        }
+    });
+}

package/dist/src/tools/contract.d.ts

@@ -0,0 +1,17 @@
+export interface ComponentContract {
+    name: string;
+    found: boolean;
+    package?: string;
+    props?: Array<{
+        name: string;
+        type: string;
+        default?: string;
+        description?: string;
+    }>;
+    tokens?: string[];
+    variants?: string[];
+    tones?: string[];
+    sizes?: string[];
+    denseUsage?: string;
+}
+export declare function dsContract(componentNames: string[], rootDir?: string): Record<string, ComponentContract>;

package/dist/src/tools/contract.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function dsContract(componentNames, rootDir = process.cwd()) {
+    const result = {};
+    const searchDirs = [
+        { pkg: '@blue-patterns/core', base: 'packages/core/src' },
+        { pkg: '@blue-patterns/charts', base: 'packages/charts/src' },
+        { pkg: '@blue-patterns/motion', base: 'packages/motion/src' },
+    ];
+    for (const name of componentNames) {
+        let found = false;
+        for (const { pkg, base } of searchDirs) {
+            const candidateDoc = path.resolve(rootDir, base, name, `${name}.doc.mjs`);
+            const directDoc = path.resolve(rootDir, base, `${name}.doc.mjs`);
+            const targetDoc = fs.existsSync(candidateDoc) ? candidateDoc : fs.existsSync(directDoc) ? directDoc : null;
+            if (targetDoc) {
+                found = true;
+                const content = fs.readFileSync(targetDoc, 'utf8');
+                // Extract description
+                const descMatch = content.match(/description:\s*['"`](.*?)['"`]/);
+                const description = descMatch ? descMatch[1] : '';
+                // Extract props roughly from JSDoc or object declaration
+                const propMatches = [...content.matchAll(/name:\s*['"`](.*?)['"`],\s*type:\s*['"`](.*?)['"`]/g)];
+                const props = propMatches.map((m) => ({
+                    name: m[1],
+                    type: m[2],
+                }));
+                // Default design tokens
+                const tokens = [];
+                const tokenMatches = [...content.matchAll(/--[a-z0-9-]+/g)];
+                for (const tm of tokenMatches) {
+                    if (!tokens.includes(tm[0]))
+                        tokens.push(tm[0]);
+                }
+                result[name] = {
+                    name,
+                    found: true,
+                    package: pkg,
+                    props: props.length > 0 ? props : [
+                        { name: 'size', type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'" },
+                        { name: 'variant', type: "'solid' | 'outline' | 'ghost' | 'soft'" },
+                        { name: 'tone', type: "'primary' | 'neutral' | 'success' | 'warning' | 'danger' | 'info'" },
+                        { name: 'motion', type: "'none' | 'subtle' | 'spring'" },
+                    ],
+                    tokens: tokens.length > 0 ? tokens : ['--color-primary-base', '--spacing-2', '--radius-md'],
+                    variants: ['solid', 'outline', 'ghost', 'soft'],
+                    tones: ['primary', 'neutral', 'success', 'warning', 'danger', 'info'],
+                    sizes: ['xs', 'sm', 'md', 'lg', 'xl'],
+                    denseUsage: `import { ${name} } from '${pkg}';\n<${name} variant="solid" tone="primary" size="md">Content</${name}>`,
+                };
+                break;
+            }
+        }
+        if (!found) {
+            result[name] = {
+                name,
+                found: false,
+            };
+        }
+    }
+    return result;
+}

package/dist/src/tools/search.d.ts

@@ -0,0 +1,8 @@
+export interface SearchResult {
+    name: string;
+    package: string;
+    category: string;
+    description: string;
+    score: number;
+}
+export declare function dsSearch(query: string, category?: string, rootDir?: string): SearchResult[];

package/dist/src/tools/search.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function dsSearch(query, category, rootDir = process.cwd()) {
+    const results = [];
+    const normalizedQuery = query.toLowerCase().trim();
+    const packagesToScan = [
+        { pkgName: '@blue-patterns/core', relDir: 'packages/core/src', defaultCategory: 'Component' },
+        { pkgName: '@blue-patterns/charts', relDir: 'packages/charts/src', defaultCategory: 'DataViz' },
+        { pkgName: '@blue-patterns/motion', relDir: 'packages/motion/src', defaultCategory: 'Motion' },
+    ];
+    for (const { pkgName, relDir, defaultCategory } of packagesToScan) {
+        const fullDir = path.resolve(rootDir, relDir);
+        if (!fs.existsSync(fullDir))
+            continue;
+        const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const docFile = path.join(fullDir, entry.name, `${entry.name}.doc.mjs`);
+                if (fs.existsSync(docFile)) {
+                    const content = fs.readFileSync(docFile, 'utf8');
+                    const nameMatch = entry.name;
+                    const descMatch = content.match(/description:\s*['"`](.*?)['"`]/);
+                    const description = descMatch ? descMatch[1] : `Component ${nameMatch}`;
+                    let score = 0;
+                    if (nameMatch.toLowerCase() === normalizedQuery)
+                        score += 100;
+                    else if (nameMatch.toLowerCase().includes(normalizedQuery))
+                        score += 50;
+                    if (description.toLowerCase().includes(normalizedQuery))
+                        score += 20;
+                    if (score > 0 || !query) {
+                        results.push({
+                            name: nameMatch,
+                            package: pkgName,
+                            category: defaultCategory,
+                            description,
+                            score,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Also include 8 Themes
+    const themes = [
+        { name: 'theme-default.css', desc: 'Balanced neutral baseline' },
+        { name: 'theme-obsidian.css', desc: 'High-contrast developer dark-first palette' },
+        { name: 'theme-editorial.css', desc: 'Warm paper surfaces + serif display typography' },
+        { name: 'theme-enterprise.css', desc: 'High-density spacing and compact scale for data-heavy SaaS' },
+        { name: 'theme-glass.css', desc: 'Translucent elevated surfaces with backdrop-filter tokens' },
+        { name: 'theme-forest.css', desc: 'Organic deep-green & warm sand tokens' },
+        { name: 'theme-cobalt.css', desc: 'Crisp fintech blue & slate hierarchy' },
+        { name: 'theme-high-contrast.css', desc: 'WCAG AAA 7:1+ contrast enforcement' },
+    ];
+    for (const th of themes) {
+        let score = 0;
+        if (th.name.toLowerCase().includes(normalizedQuery))
+            score += 60;
+        if (th.desc.toLowerCase().includes(normalizedQuery))
+            score += 25;
+        if (score > 0 || !query) {
+            results.push({
+                name: th.name,
+                package: '@blue-patterns/themes',
+                category: 'Theme',
+                description: th.desc,
+                score,
+            });
+        }
+    }
+    return results
+        .filter((r) => !category || r.category.toLowerCase() === category.toLowerCase())
+        .sort((a, b) => b.score - a.score);
+}

package/dist/src/tools/swizzle.d.ts

@@ -0,0 +1,8 @@
+export interface SwizzleResult {
+    success: boolean;
+    component: string;
+    destination: string;
+    filesCopied: string[];
+    error?: string;
+}
+export declare function dsSwizzle(componentName: string, destinationPath: string, rootDir?: string): SwizzleResult;

package/dist/src/tools/swizzle.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function dsSwizzle(componentName, destinationPath, rootDir = process.cwd()) {
+    const componentDir = path.resolve(rootDir, 'packages/core/src', componentName);
+    if (!fs.existsSync(componentDir)) {
+        return {
+            success: false,
+            component: componentName,
+            destination: destinationPath,
+            filesCopied: [],
+            error: `Component directory not found at '${componentDir}'.`,
+        };
+    }
+    const destDir = path.resolve(rootDir, destinationPath, componentName);
+    fs.mkdirSync(destDir, { recursive: true });
+    const filesCopied = [];
+    const entries = fs.readdirSync(componentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isFile()) {
+            const srcFile = path.join(componentDir, entry.name);
+            const dstFile = path.join(destDir, entry.name);
+            fs.copyFileSync(srcFile, dstFile);
+            filesCopied.push(entry.name);
+        }
+    }
+    return {
+        success: true,
+        component: componentName,
+        destination: destDir,
+        filesCopied,
+    };
+}

package/dist/src/tools/validate.d.ts

@@ -0,0 +1,12 @@
+export interface ValidationIssue {
+    type: 'hallucinated_component' | 'hardcoded_color' | 'invalid_prop' | 'untokenized_style';
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+    summary: string;
+}
+export declare function dsValidateJsx(tsxCode: string): ValidationResult;

package/dist/src/tools/validate.js

@@ -0,0 +1,58 @@
+import ts from 'typescript';
+export function dsValidateJsx(tsxCode) {
+    const issues = [];
+    const sourceFile = ts.createSourceFile('input.tsx', tsxCode, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    // 1. Check for raw hex colors in code text
+    const hexColorRegex = /#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+    let match;
+    while ((match = hexColorRegex.exec(tsxCode)) !== null) {
+        const pos = sourceFile.getLineAndCharacterOfPosition(match.index);
+        issues.push({
+            type: 'hardcoded_color',
+            message: `Hardcoded hex color '${match[0]}' detected. Use CSS custom property token like 'var(--color-primary-base)' or 'var(--color-neutral-subtle)'.`,
+            line: pos.line + 1,
+            column: pos.character + 1,
+        });
+    }
+    // 2. Check imports & JSX Elements AST
+    function visit(node) {
+        // Check imports from @blue-patterns/*
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier.getText(sourceFile).replace(/['"]/g, '');
+            if (moduleSpecifier.startsWith('@astryxdesign/')) {
+                const pos = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                issues.push({
+                    type: 'hallucinated_component',
+                    message: `Legacy import '${moduleSpecifier}'. Use re-namespaced '@blue-patterns/${moduleSpecifier.replace('@astryxdesign/', '')}'.`,
+                    line: pos.line + 1,
+                    column: pos.character + 1,
+                });
+            }
+        }
+        // Check JSX attributes for invalid styling patterns
+        if (ts.isJsxAttribute(node)) {
+            const attrName = node.name.getText(sourceFile);
+            if (attrName === 'style' && node.initializer) {
+                const text = node.initializer.getText(sourceFile);
+                if (/px\b/.test(text) && !/var\(--spacing-/.test(text)) {
+                    const pos = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                    issues.push({
+                        type: 'untokenized_style',
+                        message: `Inline hardcoded pixel value detected in style attribute. Use design tokens like 'var(--spacing-*)'.`,
+                        line: pos.line + 1,
+                        column: pos.character + 1,
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return {
+        valid: issues.length === 0,
+        issues,
+        summary: issues.length === 0
+            ? 'AST Validation Passed: 0 hallucinated components, 0 hardcoded colors, strict token compliance.'
+            : `AST Validation Failed: ${issues.length} issue(s) detected.`,
+    };
+}

package/dist/tools/contract.d.ts

@@ -0,0 +1,17 @@
+export interface ComponentContract {
+    name: string;
+    found: boolean;
+    package?: string;
+    props?: Array<{
+        name: string;
+        type: string;
+        default?: string;
+        description?: string;
+    }>;
+    tokens?: string[];
+    variants?: string[];
+    tones?: string[];
+    sizes?: string[];
+    denseUsage?: string;
+}
+export declare function dsContract(componentNames: string[], rootDir?: string): Record<string, ComponentContract>;

package/dist/tools/contract.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function dsContract(componentNames, rootDir = process.cwd()) {
+    const result = {};
+    const searchDirs = [
+        { pkg: '@blue-patterns/core', base: 'packages/core/src' },
+        { pkg: '@blue-patterns/charts', base: 'packages/charts/src' },
+        { pkg: '@blue-patterns/motion', base: 'packages/motion/src' },
+    ];
+    for (const name of componentNames) {
+        let found = false;
+        for (const { pkg, base } of searchDirs) {
+            const candidateDoc = path.resolve(rootDir, base, name, `${name}.doc.mjs`);
+            const directDoc = path.resolve(rootDir, base, `${name}.doc.mjs`);
+            const targetDoc = fs.existsSync(candidateDoc) ? candidateDoc : fs.existsSync(directDoc) ? directDoc : null;
+            if (targetDoc) {
+                found = true;
+                const content = fs.readFileSync(targetDoc, 'utf8');
+                // Extract description
+                const descMatch = content.match(/description:\s*['"`](.*?)['"`]/);
+                const description = descMatch ? descMatch[1] : '';
+                // Extract props roughly from JSDoc or object declaration
+                const propMatches = [...content.matchAll(/name:\s*['"`](.*?)['"`],\s*type:\s*['"`](.*?)['"`]/g)];
+                const props = propMatches.map((m) => ({
+                    name: m[1],
+                    type: m[2],
+                }));
+                // Default design tokens
+                const tokens = [];
+                const tokenMatches = [...content.matchAll(/--[a-z0-9-]+/g)];
+                for (const tm of tokenMatches) {
+                    if (!tokens.includes(tm[0]))
+                        tokens.push(tm[0]);
+                }
+                result[name] = {
+                    name,
+                    found: true,
+                    package: pkg,
+                    props: props.length > 0 ? props : [
+                        { name: 'size', type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'" },
+                        { name: 'variant', type: "'solid' | 'outline' | 'ghost' | 'soft'" },
+                        { name: 'tone', type: "'primary' | 'neutral' | 'success' | 'warning' | 'danger' | 'info'" },
+                        { name: 'motion', type: "'none' | 'subtle' | 'spring'" },
+                    ],
+                    tokens: tokens.length > 0 ? tokens : ['--color-primary-base', '--spacing-2', '--radius-md'],
+                    variants: ['solid', 'outline', 'ghost', 'soft'],
+                    tones: ['primary', 'neutral', 'success', 'warning', 'danger', 'info'],
+                    sizes: ['xs', 'sm', 'md', 'lg', 'xl'],
+                    denseUsage: `import { ${name} } from '${pkg}';\n<${name} variant="solid" tone="primary" size="md">Content</${name}>`,
+                };
+                break;
+            }
+        }
+        if (!found) {
+            result[name] = {
+                name,
+                found: false,
+            };
+        }
+    }
+    return result;
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,8 @@
+export interface SearchResult {
+    name: string;
+    package: string;
+    category: string;
+    description: string;
+    score: number;
+}
+export declare function dsSearch(query: string, category?: string, rootDir?: string): SearchResult[];

package/dist/tools/search.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function dsSearch(query, category, rootDir = process.cwd()) {
+    const results = [];
+    const normalizedQuery = query.toLowerCase().trim();
+    const packagesToScan = [
+        { pkgName: '@blue-patterns/core', relDir: 'packages/core/src', defaultCategory: 'Component' },
+        { pkgName: '@blue-patterns/charts', relDir: 'packages/charts/src', defaultCategory: 'DataViz' },
+        { pkgName: '@blue-patterns/motion', relDir: 'packages/motion/src', defaultCategory: 'Motion' },
+    ];
+    for (const { pkgName, relDir, defaultCategory } of packagesToScan) {
+        const fullDir = path.resolve(rootDir, relDir);
+        if (!fs.existsSync(fullDir))
+            continue;
+        const entries = fs.readdirSync(fullDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const docFile = path.join(fullDir, entry.name, `${entry.name}.doc.mjs`);
+                if (fs.existsSync(docFile)) {
+                    const content = fs.readFileSync(docFile, 'utf8');
+                    const nameMatch = entry.name;
+                    const descMatch = content.match(/description:\s*['"`](.*?)['"`]/);
+                    const description = descMatch ? descMatch[1] : `Component ${nameMatch}`;
+                    let score = 0;
+                    if (nameMatch.toLowerCase() === normalizedQuery)
+                        score += 100;
+                    else if (nameMatch.toLowerCase().includes(normalizedQuery))
+                        score += 50;
+                    if (description.toLowerCase().includes(normalizedQuery))
+                        score += 20;
+                    if (score > 0 || !query) {
+                        results.push({
+                            name: nameMatch,
+                            package: pkgName,
+                            category: defaultCategory,
+                            description,
+                            score,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Also include 8 Themes
+    const themes = [
+        { name: 'theme-default.css', desc: 'Balanced neutral baseline' },
+        { name: 'theme-obsidian.css', desc: 'High-contrast developer dark-first palette' },
+        { name: 'theme-editorial.css', desc: 'Warm paper surfaces + serif display typography' },
+        { name: 'theme-enterprise.css', desc: 'High-density spacing and compact scale for data-heavy SaaS' },
+        { name: 'theme-glass.css', desc: 'Translucent elevated surfaces with backdrop-filter tokens' },
+        { name: 'theme-forest.css', desc: 'Organic deep-green & warm sand tokens' },
+        { name: 'theme-cobalt.css', desc: 'Crisp fintech blue & slate hierarchy' },
+        { name: 'theme-high-contrast.css', desc: 'WCAG AAA 7:1+ contrast enforcement' },
+    ];
+    for (const th of themes) {
+        let score = 0;
+        if (th.name.toLowerCase().includes(normalizedQuery))
+            score += 60;
+        if (th.desc.toLowerCase().includes(normalizedQuery))
+            score += 25;
+        if (score > 0 || !query) {
+            results.push({
+                name: th.name,
+                package: '@blue-patterns/themes',
+                category: 'Theme',
+                description: th.desc,
+                score,
+            });
+        }
+    }
+    return results
+        .filter((r) => !category || r.category.toLowerCase() === category.toLowerCase())
+        .sort((a, b) => b.score - a.score);
+}

package/dist/tools/swizzle.d.ts

@@ -0,0 +1,8 @@
+export interface SwizzleResult {
+    success: boolean;
+    component: string;
+    destination: string;
+    filesCopied: string[];
+    error?: string;
+}
+export declare function dsSwizzle(componentName: string, destinationPath: string, rootDir?: string): SwizzleResult;

package/dist/tools/swizzle.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function dsSwizzle(componentName, destinationPath, rootDir = process.cwd()) {
+    const componentDir = path.resolve(rootDir, 'packages/core/src', componentName);
+    if (!fs.existsSync(componentDir)) {
+        return {
+            success: false,
+            component: componentName,
+            destination: destinationPath,
+            filesCopied: [],
+            error: `Component directory not found at '${componentDir}'.`,
+        };
+    }
+    const destDir = path.resolve(rootDir, destinationPath, componentName);
+    fs.mkdirSync(destDir, { recursive: true });
+    const filesCopied = [];
+    const entries = fs.readdirSync(componentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isFile()) {
+            const srcFile = path.join(componentDir, entry.name);
+            const dstFile = path.join(destDir, entry.name);
+            fs.copyFileSync(srcFile, dstFile);
+            filesCopied.push(entry.name);
+        }
+    }
+    return {
+        success: true,
+        component: componentName,
+        destination: destDir,
+        filesCopied,
+    };
+}

package/dist/tools/validate.d.ts

@@ -0,0 +1,12 @@
+export interface ValidationIssue {
+    type: 'hallucinated_component' | 'hardcoded_color' | 'invalid_prop' | 'untokenized_style';
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+    summary: string;
+}
+export declare function dsValidateJsx(tsxCode: string): ValidationResult;

package/dist/tools/validate.js

@@ -0,0 +1,58 @@
+import ts from 'typescript';
+export function dsValidateJsx(tsxCode) {
+    const issues = [];
+    const sourceFile = ts.createSourceFile('input.tsx', tsxCode, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    // 1. Check for raw hex colors in code text
+    const hexColorRegex = /#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+    let match;
+    while ((match = hexColorRegex.exec(tsxCode)) !== null) {
+        const pos = sourceFile.getLineAndCharacterOfPosition(match.index);
+        issues.push({
+            type: 'hardcoded_color',
+            message: `Hardcoded hex color '${match[0]}' detected. Use CSS custom property token like 'var(--color-primary-base)' or 'var(--color-neutral-subtle)'.`,
+            line: pos.line + 1,
+            column: pos.character + 1,
+        });
+    }
+    // 2. Check imports & JSX Elements AST
+    function visit(node) {
+        // Check imports from @blue-patterns/*
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier.getText(sourceFile).replace(/['"]/g, '');
+            if (moduleSpecifier.startsWith('@astryxdesign/')) {
+                const pos = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                issues.push({
+                    type: 'hallucinated_component',
+                    message: `Legacy import '${moduleSpecifier}'. Use re-namespaced '@blue-patterns/${moduleSpecifier.replace('@astryxdesign/', '')}'.`,
+                    line: pos.line + 1,
+                    column: pos.character + 1,
+                });
+            }
+        }
+        // Check JSX attributes for invalid styling patterns
+        if (ts.isJsxAttribute(node)) {
+            const attrName = node.name.getText(sourceFile);
+            if (attrName === 'style' && node.initializer) {
+                const text = node.initializer.getText(sourceFile);
+                if (/px\b/.test(text) && !/var\(--spacing-/.test(text)) {
+                    const pos = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                    issues.push({
+                        type: 'untokenized_style',
+                        message: `Inline hardcoded pixel value detected in style attribute. Use design tokens like 'var(--spacing-*)'.`,
+                        line: pos.line + 1,
+                        column: pos.character + 1,
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return {
+        valid: issues.length === 0,
+        issues,
+        summary: issues.length === 0
+            ? 'AST Validation Passed: 0 hallucinated components, 0 hardcoded colors, strict token compliance.'
+            : `AST Validation Failed: ${issues.length} issue(s) detected.`,
+    };
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@blue-patterns/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.18",
+  "description": "Deterministic Model Context Protocol (MCP) server exposing Blue-Patterns-UI contracts, validation, and search to AI coding agents",
+  "author": "Blue-Patterns-UI Contributors",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "blue-patterns-mcp": "./bin/mcp-server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "typescript": "^5.0.0 || ^6.0.0"
+  },
+  "homepage": "https://github.com/Sandeep-Hipparagi/blue-patterns-ui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sandeep-Hipparagi/blue-patterns-ui.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Sandeep-Hipparagi/blue-patterns-ui/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node bin/mcp-server.js",
+    "typecheck": "tsc --noEmit"
+  }
 }