openuispec 0.1.33 → 0.1.35

package/README.md

@@ -52,7 +52,7 @@ cd your-project
 openuispec init
 ```
 
-This scaffolds a spec directory, starter tokens, and adds rules to `CLAUDE.md` / `AGENTS.md` so AI assistants track spec changes automatically.
+This scaffolds a spec directory, starter tokens, adds rules to `CLAUDE.md` / `AGENTS.md`, and configures the MCP server in `.claude.json` so AI assistants track spec changes automatically.
 Use `openuispec init --no-configure-targets` if you want to scaffold first and choose target stacks later.
 
 Then hand your spec to any AI code generator:
@@ -116,10 +116,16 @@ openuispec/
 ├── cli/                                 # CLI tool (openuispec init, drift, prepare, validate)
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
+├── mcp-server/                          # MCP server (openuispec-mcp)
+│   └── index.ts                        # Stdio transport, 5 tools
+├── check/                               # Composite validation command
+│   └── index.ts                        # Schema + semantic + readiness
 ├── drift/                               # Drift detection (spec change tracking)
 │   └── index.ts                        # Hash-based drift checker
 ├── prepare/                             # Target work bundle generation
 │   └── index.ts                        # Baseline-aware target preparation
+├── status/                              # Cross-target status summary
+│   └── index.ts                        # Baseline/drift overview
 ├── LICENSE
 └── README.md
 ```
@@ -239,6 +245,41 @@ to see which targets are already up to date and which ones still need to catch u
 
 `drift --snapshot` is bookkeeping. It does not prove that the target code matches the spec, and it will not create a missing target output directory for you.
 
+## MCP server
+
+OpenUISpec includes an MCP (Model Context Protocol) server that exposes CLI commands as tools for AI assistants. This is the recommended way to integrate with Claude Code and other MCP-compatible clients — tools are called more reliably than CLAUDE.md instructions.
+
+### Setup
+
+`openuispec init` automatically configures the MCP server in `.claude.json`. For existing projects, add it manually:
+
+```json
+{
+  "mcpServers": {
+    "openuispec": {
+      "command": "npx",
+      "args": ["openuispec-mcp"]
+    }
+  }
+}
+```
+
+Or run directly: `npx openuispec-mcp`
+
+Set `OPENUISPEC_PROJECT_DIR` to override the working directory.
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `openuispec_prepare` | Build AI-ready work bundle for a target. **Call before any UI code generation.** |
+| `openuispec_check` | Schema validation + semantic lint + prepare readiness. Call after spec edits. |
+| `openuispec_status` | Cross-target summary: baselines, drift, next steps. |
+| `openuispec_validate` | Schema-only validation, optionally filtered by group. |
+| `openuispec_drift` | Detect spec drift since last snapshot, with optional semantic explanation. |
+
+All tools return structured JSON. The server includes protocol-level instructions that tell AI assistants to call `openuispec_prepare` before any UI work — this works independently of CLAUDE.md rules.
+
 ## Spec at a glance
 
 | Section | What it defines |
@@ -289,6 +330,7 @@ to see which targets are already up to date and which ones still need to catch u
 - [x] Form system (validation rules, field dependencies)
 - [x] Drift detection (spec change tracking per platform)
 - [x] CLI tool (`openuispec init` for project scaffolding + AI rules)
+- [x] MCP server for AI tool integration (`openuispec-mcp`)
 - [x] Multi-platform showcase app (`examples/todo-orbit/`)
 - [ ] More example apps (e-commerce, social, dashboard)
 

package/check/index.ts

@@ -0,0 +1,287 @@
+#!/usr/bin/env tsx
+/**
+ * Composite check command for OpenUISpec projects.
+ *
+ * Combines schema validation, semantic linting, and prepare readiness
+ * into a single call for AI agents.
+ *
+ * Usage:
+ *   openuispec check --target web           # human-readable summary
+ *   openuispec check --target ios --json    # machine-readable output
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+import {
+  findProjectDir,
+  readManifest,
+  readProjectName,
+  resolveOutputDir,
+} from "../drift/index.js";
+import {
+  buildAjv,
+  readIncludes,
+  GROUPS,
+  type JsonGroupResult,
+} from "../schema/validate.js";
+import { collectSemanticLint } from "../schema/semantic-lint.js";
+
+// ── types ─────────────────────────────────────────────────────────────
+
+interface CheckValidation {
+  total_errors: number;
+  groups: JsonGroupResult[];
+}
+
+interface CheckSemantic {
+  total_errors: number;
+  errors: Array<{ path: string; message: string }>;
+}
+
+interface CheckPrepare {
+  mode: "bootstrap" | "update";
+  ready: boolean;
+  missing: string[];
+  warnings: string[];
+}
+
+export interface CheckResult {
+  target: string;
+  validation: CheckValidation;
+  semantic: CheckSemantic;
+  prepare: CheckPrepare;
+}
+
+// ── prepare readiness helpers ─────────────────────────────────────────
+
+const PRESENTATION_ONLY_KEYS = new Set(["naming", "bundler", "css"]);
+
+function platformStackKeys(target: string): string[] {
+  switch (target) {
+    case "android":
+      return ["architecture", "state", "preferences", "database", "di", "naming"];
+    case "web":
+      return ["runtime", "routing", "state", "storage_backend", "bundler", "css", "naming"];
+    case "ios":
+      return ["architecture", "persistence", "di", "naming"];
+    default:
+      return [];
+  }
+}
+
+function requiredPlatformDecisionKeys(target: string): string[] {
+  return platformStackKeys(target).filter((key) => !PRESENTATION_ONLY_KEYS.has(key));
+}
+
+function readPlatformDefinition(
+  projectDir: string,
+  manifest: Record<string, any>,
+  target: string,
+): Record<string, any> {
+  const platformDir = resolve(projectDir, manifest.includes?.platform ?? "./platform/");
+  const platformPath = join(platformDir, `${target}.yaml`);
+  if (!existsSync(platformPath)) return {};
+  try {
+    const doc = YAML.parse(readFileSync(platformPath, "utf-8"));
+    return doc?.[target] ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function missingPlatformDecisions(
+  target: string,
+  platformDef: Record<string, any>,
+): string[] {
+  const generation = platformDef.generation ?? {};
+  return requiredPlatformDecisionKeys(target).filter((key) => {
+    const value = generation[key];
+    return typeof value !== "string" || value.trim().length === 0;
+  });
+}
+
+function hasApiEndpoints(manifest: Record<string, any>): boolean {
+  const endpoints = manifest.api?.endpoints;
+  return typeof endpoints === "object" && endpoints !== null && Object.keys(endpoints).length > 0;
+}
+
+function resolveBackendRoot(
+  projectDir: string,
+  manifest: Record<string, any>,
+): string | null {
+  const backendRoot = manifest.generation?.code_roots?.backend;
+  if (typeof backendRoot !== "string" || backendRoot.trim().length === 0) {
+    return null;
+  }
+  return resolve(projectDir, backendRoot);
+}
+
+function determinePrepare(
+  projectDir: string,
+  projectName: string,
+  target: string,
+): CheckPrepare {
+  const manifest = readManifest(projectDir);
+  const outputDir = resolveOutputDir(projectDir, projectName, target);
+  const statePath = join(outputDir, ".openuispec-state.json");
+  const snapshotExists = existsSync(statePath);
+  const mode: "bootstrap" | "update" = snapshotExists ? "update" : "bootstrap";
+
+  const platformDef = readPlatformDefinition(projectDir, manifest, target);
+  const missing = missingPlatformDecisions(target, platformDef);
+  const warnings: string[] = [];
+
+  const backendContextRequired = hasApiEndpoints(manifest);
+  const backendRoot = resolveBackendRoot(projectDir, manifest);
+  const backendContextReady =
+    !backendContextRequired || (backendRoot !== null && existsSync(backendRoot));
+
+  if (!backendContextReady) {
+    warnings.push(
+      "api endpoints require generation.code_roots.backend to point at an existing backend folder",
+    );
+  }
+
+  const stackConfirmation = platformDef.generation?.stack_confirmation;
+  const pendingUserConfirmation =
+    typeof stackConfirmation === "string" && stackConfirmation !== "confirmed";
+
+  if (pendingUserConfirmation) {
+    warnings.push(
+      `Target stack for "${target}" requires explicit user confirmation before implementation.`,
+    );
+  }
+
+  const ready =
+    missing.length === 0 && backendContextReady && !pendingUserConfirmation;
+
+  return { mode, ready, missing, warnings };
+}
+
+// ── core (importable, no process.exit) ───────────────────────────────
+
+export function buildCheckResult(target: string, cwd: string = process.cwd()): CheckResult {
+  const projectDir = findProjectDir(cwd);
+  const projectName = readProjectName(projectDir);
+  const includes = readIncludes(projectDir);
+  const ajv = buildAjv();
+
+  // 1. Schema validation (all groups except semantic)
+  const schemaGroupKeys = Object.keys(GROUPS).filter((k) => k !== "semantic");
+  const validationGroups: JsonGroupResult[] = [];
+  let validationTotalErrors = 0;
+
+  for (const key of schemaGroupKeys) {
+    const result = GROUPS[key].collectJson(ajv, projectDir, includes, key);
+    validationGroups.push(result);
+    validationTotalErrors += result.errors.length;
+  }
+
+  const validation: CheckValidation = {
+    total_errors: validationTotalErrors,
+    groups: validationGroups,
+  };
+
+  // 2. Semantic validation
+  const semanticErrors = collectSemanticLint(projectDir, includes);
+  const semantic: CheckSemantic = {
+    total_errors: semanticErrors.length,
+    errors: semanticErrors.map((e) => ({ path: e.path, message: e.message })),
+  };
+
+  // 3. Prepare readiness
+  const prepare = determinePrepare(projectDir, projectName, target);
+
+  return { target, validation, semantic, prepare };
+}
+
+// ── main ──────────────────────────────────────────────────────────────
+
+export function runCheck(argv: string[]): void {
+  const isJson = argv.includes("--json");
+  const targetIdx = argv.indexOf("--target");
+  const target =
+    targetIdx !== -1 && argv[targetIdx + 1] ? argv[targetIdx + 1] : null;
+
+  if (!target) {
+    console.error("Error: --target is required for check");
+    console.error("Usage: openuispec check --target <target> [--json]");
+    process.exit(1);
+  }
+
+  const result = buildCheckResult(target);
+
+  if (isJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printReport(result);
+  }
+
+  // Exit codes: 0 = clean + ready, 2 = validation errors, 1 = config error
+  const totalErrors = result.validation.total_errors + result.semantic.total_errors;
+  if (totalErrors > 0) {
+    process.exit(2);
+  }
+  if (!result.prepare.ready) {
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+function printReport(result: CheckResult): void {
+  console.log("OpenUISpec Check");
+  console.log("================");
+  console.log(`Target: ${result.target}`);
+
+  const totalValidation = result.validation.total_errors;
+  const totalSemantic = result.semantic.total_errors;
+
+  console.log(`\nSchema validation: ${totalValidation === 0 ? "PASS" : `FAIL (${totalValidation} error(s))`}`);
+  if (totalValidation > 0) {
+    for (const group of result.validation.groups) {
+      if (group.errors.length > 0) {
+        console.log(`  ${group.group}: ${group.errors.length} error(s)`);
+        for (const err of group.errors.slice(0, 3)) {
+          console.log(`    [${err.file}] ${err.path}: ${err.message}`);
+        }
+        if (group.errors.length > 3) {
+          console.log(`    ... and ${group.errors.length - 3} more`);
+        }
+      }
+    }
+  }
+
+  console.log(`Semantic lint: ${totalSemantic === 0 ? "PASS" : `FAIL (${totalSemantic} error(s))`}`);
+  if (totalSemantic > 0) {
+    for (const err of result.semantic.errors.slice(0, 5)) {
+      console.log(`  [${err.path}] ${err.message}`);
+    }
+    if (result.semantic.errors.length > 5) {
+      console.log(`  ... and ${result.semantic.errors.length - 5} more`);
+    }
+  }
+
+  console.log(`\nPrepare readiness: ${result.prepare.ready ? "READY" : "NOT READY"}`);
+  console.log(`  Mode: ${result.prepare.mode}`);
+  if (result.prepare.missing.length > 0) {
+    console.log(`  Missing platform decisions: ${result.prepare.missing.join(", ")}`);
+  }
+  for (const w of result.prepare.warnings) {
+    console.log(`  Warning: ${w}`);
+  }
+
+  const totalErrors = result.validation.total_errors + result.semantic.total_errors;
+  console.log(
+    `\nResult: ${totalErrors === 0 && result.prepare.ready ? "ALL CLEAR" : "ACTION NEEDED"}`,
+  );
+}
+
+// Direct execution
+const isDirectRun =
+  process.argv[1]?.endsWith("check/index.ts") ||
+  process.argv[1]?.endsWith("check/index.js");
+
+if (isDirectRun) {
+  runCheck(process.argv.slice(2));
+}

package/cli/init.ts

@@ -261,12 +261,23 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 3. \`examples/taskflow/openuispec/\` — complete working example with all file types
 4. \`schema/\` — JSON Schemas for validation
 
+## MCP Tools (recommended for AI assistants)
+
+When the openuispec MCP server is configured (see \`.claude.json\`), AI assistants should use these tools instead of CLI commands:
+
+| Tool | When to use |
+|------|-------------|
+| \`openuispec_prepare\` | **Before any UI code generation.** Returns spec context, platform config, and constraints. |
+| \`openuispec_check\` | After editing spec files. Validates schema + semantics + readiness. |
+| \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
+| \`openuispec_validate\` | Schema-only validation, optionally by group. |
+| \`openuispec_drift\` | Detect spec changes since last snapshot. |
+
 ## CLI commands
 
 \`\`\`bash
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Run semantic cross-reference linting
-openuispec validate screens     # Validate only screens
 openuispec configure-target ${targets[0]} [--defaults] # Configure target stack; --defaults stays unconfirmed
 openuispec status               # Show cross-target baseline/drift status
 openuispec drift --target ${targets[0]} --explain   # Explain semantic spec drift
@@ -298,111 +309,90 @@ ${RULES_START_MARKER}
 # Spec files are the single source of truth for all UI across platforms.
 # Targets: ${targetList}
 
-## IMPORTANT — Read the specification before working with spec files
+## MANDATORY — UI work requires OpenUISpec tools
 
-The spec format, file schemas, and generation rules are defined in the installed \`openuispec\` package.
-You MUST read the reference files listed below before creating, editing, or generating from any spec file.
-Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+When the user's request involves UI — screens, navigation, layout, tokens, flows, localization,
+or any visual/structural change — you MUST use the OpenUISpec tools before writing any code.
 
-**Find the package in this order:**
-1. \`node_modules/openuispec/\` (project dependency)
-2. Run \`npm root -g\` → \`<prefix>/openuispec/\` (global install)
-3. Online: \`https://openuispec.rsteam.uz/llms-full.txt\` (if not installed)
+### MCP Tools (use these when available)
 
-**Reference files inside the package (read in this order):**
-1. \`README.md\` — schema tables, file format reference, root wrapper keys
-2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. \`examples/taskflow/openuispec/\` — complete working example with all file types
-4. \`schema/\` — JSON Schemas for every file type
+Call these MCP tools directly. They return structured JSON with everything you need.
 
-These files are updated with each package version. Always read from the installed package,
-not from cached or memorized content, to ensure you use the latest spec.
+1. **Before ANY UI code generation or modification:**
+   Call \`openuispec_prepare\` with the target platform. This returns the spec context,
+   platform config, generation constraints, and semantic changes. Do not skip this step.
 
-## What is OpenUISpec
-OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
+2. **After editing spec files:**
+   Call \`openuispec_check\` to validate schema + semantic lint + prepare readiness.
 
-## Spec location
-- Spec root: \`${specDir}/\`
-- Manifest: \`${specDir}/openuispec.yaml\` — always read this first.
-- Tokens: \`${specDir}/tokens/\`
-- Screens: \`${specDir}/screens/\`
-- Flows: \`${specDir}/flows/\`
-- Contracts: \`${specDir}/contracts/\`
-- Platform: \`${specDir}/platform/\`
-- Locales: \`${specDir}/locales/\`
+3. **To understand project state:**
+   Call \`openuispec_status\` for cross-target summary.
 
-**Note:** These are the default paths. Actual paths are in \`includes:\` in \`openuispec.yaml\` and may use relative paths. Always read \`openuispec.yaml\` to find the real directories.
+4. **To detect what changed:**
+   Call \`openuispec_drift\` with \`explain: true\` to see property-level spec changes.
 
-## If spec directories are empty (first-time setup)
-This means the project has existing UI code but hasn't been specced yet. Your job:
-
-1. **Read the spec first** — find and read \`spec/openuispec-v0.1.md\` from the installed package.
-2. **Find existing screens** — scan the codebase for UI screen files.
-3. **Create stubs** — for each screen, create \`${specDir}/screens/<name>.yaml\` with:
-   \`\`\`yaml
-   screen_name:
-     semantic: "Brief description of what this screen does"
-     status: stub
-     layout:
-       type: scroll_vertical
-   \`\`\`
-4. **Extract tokens** — scan for colors, fonts, spacing and create files in \`${specDir}/tokens/\`.
-5. **Update the manifest** — fill in \`data_model\`, \`api.endpoints\`, and \`generation.code_roots.backend\` in \`${specDir}/openuispec.yaml\`.
-
-## OpenUISpec Source Of Truth
-
-OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
-
-### Start from spec when:
-- the request changes screen structure
-- the request changes navigation
-- the request changes fields, actions, validation, or data binding
-- the request changes tokens, variants, contracts, flows, or localization
-- the request affects more than one platform
-- the request is phrased in product/UI terms rather than platform-code terms
-
-Spec-first workflow:
-1. Read \`${specDir}/openuispec.yaml\` and the relevant spec files first.
-2. Update the spec first.
-3. Update the affected generated/native UI code to match the spec.
-4. Run \`openuispec validate\`.
-5. Run \`openuispec validate semantic\`.
-6. Run \`openuispec drift --target <target> --explain\` to inspect semantic changes since that target's baseline.
-7. Run \`openuispec prepare --target <target>\` to build the target work bundle for that target. In \`bootstrap\` mode it provides first-generation constraints; in \`update\` mode it provides drift-based update scope.
-   If the target stack was filled from defaults, stop and ask the user to confirm or change it before implementation.
-8. Verify the affected UI targets build/run if possible.
-9. Only then run \`openuispec drift --snapshot --target <target>\` for affected targets, after that target output directory exists.
-10. Run \`openuispec drift --target <target> --explain\` again to confirm no spec changes remain for that target.
-11. Use \`openuispec status\` to see which other targets are still behind the updated spec.
-
-### Start from platform code when:
-- the change is platform-specific polish
-- the change is a local bug fix that does not alter shared semantic behavior
-- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
-
-Platform-first workflow:
-1. Update native/platform code.
-2. If the change affects shared semantics, sync the spec afterward.
-3. If the change is intentionally platform-specific, document it in \`platform/*.yaml\` when appropriate.
-
-### Never do this:
-- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
-- Do not treat \`openuispec drift\` as proof that generated UI matches the spec.
-- Do not skip \`--explain\` / \`prepare\` when another platform needs to catch up with shared spec changes.
-- Do not modify generated UI without checking whether the spec must change first.
-- Do not use \`configure-target --defaults\` as silent approval for implementation. Ask the user to confirm the stack first.
+5. **For schema validation only:**
+   Call \`openuispec_validate\` optionally with specific groups.
 
-## CLI commands
+### CLI fallback (when MCP is not available)
+
+If MCP tools are not available, use these CLI commands with \`--json\` flag:
+- \`openuispec prepare --target <t> --json\` — build AI-ready work bundle
+- \`openuispec check --target <t> --json\` — composite validation
+- \`openuispec status --json\` — cross-target status
+- \`openuispec drift --target <t> --explain --json\` — semantic drift
+- \`openuispec validate [group...] --json\` — schema validation
+
+### Other CLI commands
 - \`openuispec init\` — scaffold a new spec project
-- \`openuispec validate [group...]\` — validate spec files against schemas
-- \`openuispec validate semantic\` — run semantic cross-reference linting
-- \`openuispec drift --target <t>\` — check for spec drift
-- \`openuispec drift --target <t> --explain\` — explain semantic spec drift since the target baseline
-- \`openuispec drift --snapshot --target <t>\` — snapshot current state after the target output exists
-- \`openuispec prepare --target <t>\` — build the target work bundle and check whether stack confirmation is still pending
-- \`openuispec status\` — show cross-target baseline/drift status
+- \`openuispec drift --snapshot --target <t>\` — snapshot current state (only after UI code is updated)
+- \`openuispec configure-target <t>\` — configure target platform stack
 - \`openuispec update-rules\` — update AI rules to match installed package version
-- \`openuispec drift --all\` — include stubs in drift check
+
+## Spec format reference
+
+The spec format, schemas, and generation rules are in the installed \`openuispec\` package.
+You MUST read the reference files before creating or editing spec files — do NOT guess the format.
+
+**Find the package:** \`node_modules/openuispec/\` or run \`npm root -g\` → \`<prefix>/openuispec/\`.
+**Online fallback:** \`https://openuispec.rsteam.uz/llms-full.txt\`
+
+**Reference files (read in order):**
+1. \`README.md\` — schema tables, file format, root wrapper keys
+2. \`spec/openuispec-v0.1.md\` — full specification
+3. \`examples/taskflow/openuispec/\` — complete working example
+4. \`schema/\` — JSON Schemas for every file type
+
+## Spec location
+- Spec root: \`${specDir}/\` — read \`${specDir}/openuispec.yaml\` first for actual paths.
+- Default dirs: tokens/, screens/, flows/, contracts/, platform/, locales/
+
+## When to start from spec vs platform code
+
+**Spec-first** (use \`openuispec_prepare\` or \`openuispec prepare\`):
+- Screen structure, navigation, fields, actions, validation, data binding changes
+- Token, variant, contract, flow, or localization changes
+- Changes affecting multiple platforms
+- Requests in product/UI terms
+
+**Platform-first** (skip spec tools):
+- Platform-specific polish (iOS-only, Android-only, web-only)
+- Local bug fixes that don't alter shared semantic behavior
+
+## If spec directories are empty (first-time setup)
+
+Read \`spec/openuispec-v0.1.md\` from the package first, then:
+1. Scan codebase for UI screens → create \`${specDir}/screens/<name>.yaml\` as \`status: stub\`
+2. Extract tokens (colors, fonts, spacing) → \`${specDir}/tokens/\`
+3. Create contract extensions → \`${specDir}/contracts/\`
+4. Create locale files → \`${specDir}/locales/<locale>.json\`
+5. Fill in \`data_model\`, \`api.endpoints\` in \`${specDir}/openuispec.yaml\`
+
+## Rules
+- Do not snapshot drift unless the UI code has also been updated.
+- Do not modify generated UI without checking whether the spec must change first.
+- Do not use \`configure-target --defaults\` as silent approval — ask the user to confirm.
+- Always read spec format from the installed package, not from cached/memorized content.
 ${RULES_END_MARKER}
 `;
 }
@@ -479,6 +469,30 @@ export function updateRules(): void {
   } else {
     console.log(`\nAI rules updated to v${version}`);
   }
+
+  // Ensure MCP server is configured
+  const claudeJsonPath = join(cwd, ".claude.json");
+  const mcpConfig = {
+    command: "npx",
+    args: ["openuispec-mcp"],
+  };
+
+  try {
+    let claudeJson: Record<string, any> = {};
+    try {
+      claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+    } catch {
+      // file doesn't exist or isn't valid JSON — start fresh
+    }
+    if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
+    if (!claudeJson.mcpServers.openuispec) {
+      claudeJson.mcpServers.openuispec = mcpConfig;
+      writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2) + "\n");
+      console.log(`  create .claude.json (MCP server configured)`);
+    }
+  } catch {
+    // non-critical — skip silently
+  }
 }
 
 /**
@@ -744,6 +758,33 @@ export async function init(argv: string[] = []): Promise<void> {
       }
     }
 
+    // ── MCP server configuration ────────────────────────────────────
+
+    const claudeJsonPath = join(cwd, ".claude.json");
+    const mcpConfig = {
+      command: "npx",
+      args: ["openuispec-mcp"],
+    };
+
+    try {
+      let claudeJson: Record<string, any> = {};
+      try {
+        claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+      } catch {
+        // file doesn't exist or isn't valid JSON — start fresh
+      }
+      if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
+      if (!claudeJson.mcpServers.openuispec) {
+        claudeJson.mcpServers.openuispec = mcpConfig;
+        writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2) + "\n");
+        if (!quiet) console.log(`  create .claude.json (MCP server configured)`);
+      } else {
+        if (!quiet) console.log(`  skip .claude.json (openuispec MCP already configured)`);
+      }
+    } catch {
+      if (!quiet) console.log(`  skip .claude.json (could not configure MCP server)`);
+    }
+
     if (answers.configureTargets) {
       if (!quiet) console.log("\nConfiguring target stacks...\n");
       const { runConfigureTarget } = await import("./configure-target.js");
@@ -762,10 +803,14 @@ Done! Your spec project is ready at ./${answers.specDir}/
 
 Getting started (new project):
   1. Edit ${answers.specDir}/openuispec.yaml — define your data model and API
-  2. Create screens in ${answers.specDir}/screens/ (one YAML per screen)
-  3. Create flows in ${answers.specDir}/flows/ (multi-step navigation)
-  4. Ask AI to generate native code from the spec
-  5. Run \`openuispec drift --snapshot --target ${answers.targets[0]}\` to baseline the first accepted target state after that target output directory exists
+  2. Create tokens in ${answers.specDir}/tokens/ (colors, typography, spacing, etc.)
+  3. Create contract extensions in ${answers.specDir}/contracts/ (visual variants for the 7 built-in contracts)
+  4. Create screens in ${answers.specDir}/screens/ (one YAML per screen)
+  5. Create flows in ${answers.specDir}/flows/ (multi-step navigation)
+  6. Create locale files in ${answers.specDir}/locales/ (one JSON per supported locale)
+  7. Run \`openuispec validate\` and \`openuispec validate semantic\` to check everything
+  8. Ask AI to generate native code from the spec
+  9. Run \`openuispec drift --snapshot --target ${answers.targets[0]}\` to baseline the first accepted target state after that target output directory exists
 
 Getting started (existing project):
   1. Ask AI to read your existing UI code and generate spec files:
@@ -785,6 +830,7 @@ Commands:
   openuispec drift --snapshot --target ios   Save current state + git baseline after target output exists
 
 AI rules have been added to CLAUDE.md and AGENTS.md.
+MCP server configured in .claude.json (AI assistants will use openuispec tools automatically).
 
 Docs: https://openuispec.rsteam.uz
 `);

package/drift/index.ts

@@ -137,8 +137,7 @@ export function hasStatusSemantics(relPath: string): boolean {
 export function discoverSpecFiles(projectDir: string): string[] {
   const manifest = join(projectDir, "openuispec.yaml");
   if (!existsSync(manifest)) {
-    console.error(`Error: No openuispec.yaml found in ${projectDir}`);
-    process.exit(1);
+    throw new Error(`No openuispec.yaml found in ${projectDir}`);
   }
 
   const doc = YAML.parse(readFileSync(manifest, "utf-8"));
@@ -433,11 +432,10 @@ export function findProjectDir(cwd: string): string {
       return dir;
     }
   }
-  console.error(
-    "Error: No openuispec.yaml found.\n" +
+  throw new Error(
+    "No openuispec.yaml found. " +
       "Run from a directory containing openuispec.yaml or an openuispec/ subdirectory."
   );
-  process.exit(1);
 }
 
 /** Read and parse the manifest YAML. */
@@ -655,8 +653,7 @@ export function loadTargetDrift(
   const projectName = readProjectName(projectDir);
   const statePath = stateFilePath(projectDir, projectName, target);
   if (!existsSync(statePath)) {
-    console.error(missingSnapshotMessage(cwd, projectDir, projectName, target));
-    process.exit(1);
+    throw new Error(missingSnapshotMessage(cwd, projectDir, projectName, target));
   }
 
   const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));

package/mcp-server/index.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * OpenUISpec MCP Server
+ *
+ * Exposes OpenUISpec CLI commands as MCP tools so AI assistants
+ * can call them directly instead of relying on CLAUDE.md instructions.
+ *
+ * Usage:
+ *   npx openuispec-mcp                           # stdio transport
+ *   OPENUISPEC_PROJECT_DIR=/path npx openuispec-mcp  # explicit project dir
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SUPPORTED_TARGETS } from "../drift/index.js";
+import { buildPrepareResult } from "../prepare/index.js";
+import { buildCheckResult } from "../check/index.js";
+import { buildStatusResult } from "../status/index.js";
+import { buildValidateResult } from "../schema/validate.js";
+import { loadTargetDrift } from "../drift/index.js";
+
+// ── resolve project cwd ──────────────────────────────────────────────
+
+const projectCwd = process.env.OPENUISPEC_PROJECT_DIR || process.cwd();
+
+// ── read package version ─────────────────────────────────────────────
+
+function getPackageVersion(): string {
+  try {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// ── shared tool helpers ──────────────────────────────────────────────
+
+const targetSchema = z.enum(SUPPORTED_TARGETS).describe("Target platform");
+
+function formatError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function toolResult(data: unknown): { content: [{ type: "text"; text: string }] } {
+  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+}
+
+function toolError(err: unknown): { content: [{ type: "text"; text: string }]; isError: true } {
+  return { content: [{ type: "text" as const, text: `Error: ${formatError(err)}` }], isError: true };
+}
+
+// ── create server ────────────────────────────────────────────────────
+
+const server = new McpServer(
+  {
+    name: "openuispec",
+    version: getPackageVersion(),
+  },
+  {
+    instructions: `This project uses OpenUISpec — a semantic UI specification format.
+Spec files (YAML) are the single source of truth for all UI across platforms.
+
+MANDATORY WORKFLOW for any UI-related request (screens, navigation, layout, tokens, flows, localization):
+1. BEFORE writing or modifying any UI code, call openuispec_prepare with the target platform.
+   This returns the spec context, platform config, and generation constraints you must follow.
+2. If the request requires spec changes, update the spec files FIRST, then call openuispec_check to validate.
+3. Only then generate or update the platform UI code based on the prepare output.
+
+Skip these tools ONLY when the request is purely non-UI (API logic, database, infrastructure, etc.)
+or explicitly platform-specific polish that doesn't affect shared UI semantics.`,
+  }
+);
+
+// ── tool: openuispec_prepare ─────────────────────────────────────────
+
+server.registerTool(
+  "openuispec_prepare",
+  {
+    description: "Build AI-ready work bundle for a target platform. REQUIRED before any UI code generation. Returns spec context, platform config, semantic changes, and generation constraints.",
+    inputSchema: { target: targetSchema },
+  },
+  async ({ target }) => {
+    try {
+      return toolResult(buildPrepareResult(target, projectCwd));
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_check ───────────────────────────────────────────
+
+server.registerTool(
+  "openuispec_check",
+  {
+    description: "Run composite validation: schema validation, semantic linting, and prepare readiness check. Call after spec edits to verify correctness.",
+    inputSchema: { target: targetSchema },
+  },
+  async ({ target }) => {
+    try {
+      return toolResult(buildCheckResult(target, projectCwd));
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_status ──────────────────────────────────────────
+
+server.registerTool(
+  "openuispec_status",
+  {
+    description: "Show cross-target status summary: baseline, drift, and recommended next steps for all configured targets. Good starting point to understand project state.",
+  },
+  async () => {
+    try {
+      return toolResult(buildStatusResult(projectCwd));
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_validate ────────────────────────────────────────
+
+server.registerTool(
+  "openuispec_validate",
+  {
+    description: "Validate spec files against JSON schemas. Returns validation errors grouped by type (manifest, tokens, screens, flows, platform, locales, contracts, semantic).",
+    inputSchema: {
+      groups: z
+        .array(z.enum(["manifest", "tokens", "screens", "flows", "platform", "locales", "contracts", "semantic"]))
+        .optional()
+        .describe("Specific groups to validate. If omitted, validates all groups."),
+    },
+  },
+  async ({ groups }) => {
+    try {
+      return toolResult(buildValidateResult(groups, projectCwd));
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_drift ───────────────────────────────────────────
+
+server.registerTool(
+  "openuispec_drift",
+  {
+    description: "Detect spec drift since last snapshot. Shows which spec files changed, were added, or removed. Use explain to see property-level changes.",
+    inputSchema: {
+      target: targetSchema,
+      explain: z.boolean().optional().default(false).describe("Include semantic explanation of changes"),
+    },
+  },
+  async ({ target, explain }) => {
+    try {
+      const { result } = loadTargetDrift(projectCwd, target, false, explain);
+      return toolResult(result);
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── start server ─────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Failed to start OpenUISpec MCP server:", err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",
@@ -11,7 +11,9 @@
   },
   "files": [
     "cli/",
+    "check/",
     "drift/",
+    "mcp-server/",
     "prepare/",
     "status/",
     "schema/",
@@ -22,7 +24,8 @@
     "LICENSE"
   ],
   "bin": {
-    "openuispec": "./cli/index.ts"
+    "openuispec": "./cli/index.ts",
+    "openuispec-mcp": "./mcp-server/index.ts"
   },
   "scripts": {
     "test": "node --import tsx --test tests/*.test.ts",
@@ -40,6 +43,7 @@
     "postinstall": "echo \"\\n  ✓ openuispec installed — if upgrading, run: openuispec update-rules\\n\""
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "tsx": "^4.19.4",

package/prepare/index.ts

@@ -116,7 +116,7 @@ interface PrepareBootstrapBundle {
   reference_examples: string[];
 }
 
-interface PrepareResult {
+export interface PrepareResult {
   mode: "bootstrap" | "update";
   project: string;
   target: string;
@@ -1180,8 +1180,7 @@ function buildUpdatePrepareResult(cwd: string, target: string): PrepareResult {
   };
 }
 
-function buildPrepareResult(target: string): PrepareResult {
-  const cwd = process.cwd();
+export function buildPrepareResult(target: string, cwd: string = process.cwd()): PrepareResult {
   const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const outputDir = resolveOutputDir(projectDir, projectName, target);

package/schema/validate.ts

@@ -755,6 +755,36 @@ function findProjectDir(cwd: string): string {
 export { buildAjv, readIncludes, GROUPS };
 export type { JsonGroupResult, JsonError };
 
+interface ValidateResult {
+  total_errors: number;
+  groups: JsonGroupResult[];
+}
+
+export function buildValidateResult(
+  groups?: string[],
+  cwd: string = process.cwd(),
+): ValidateResult {
+  const projectDir = findProjectDir(cwd);
+  const includes = readIncludes(projectDir);
+  const ajv = buildAjv();
+
+  const keys =
+    groups && groups.length > 0
+      ? groups.filter((k) => k in GROUPS)
+      : Object.keys(GROUPS);
+
+  const results: JsonGroupResult[] = [];
+  let totalErrors = 0;
+
+  for (const key of keys) {
+    const result = GROUPS[key].collectJson(ajv, projectDir, includes, key);
+    results.push(result);
+    totalErrors += result.errors.length;
+  }
+
+  return { total_errors: totalErrors, groups: results };
+}
+
 export function runValidate(argv: string[]): void {
   const jsonMode = argv.includes("--json");
   const filteredArgs = argv.filter((a) => a !== "--json");

package/status/index.ts

@@ -45,7 +45,7 @@ interface TargetStatus {
   note?: string;
 }
 
-interface StatusResult {
+export interface StatusResult {
   project: string;
   targets: TargetStatus[];
 }
@@ -141,8 +141,7 @@ function buildTargetStatus(cwd: string, projectDir: string, projectName: string,
   };
 }
 
-function buildStatusResult(): StatusResult {
-  const cwd = process.cwd();
+export function buildStatusResult(cwd: string = process.cwd()): StatusResult {
   const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const targets = allTargets(projectDir, projectName).map((target) =>
@@ -187,7 +186,7 @@ function printReport(result: StatusResult): void {
 
 export function runStatus(argv: string[]): void {
   const isJson = argv.includes("--json");
-  const result = buildStatusResult();
+  const result = buildStatusResult(process.cwd());
 
   if (isJson) {
     console.log(JSON.stringify(result, null, 2));