jui-tools-mcp-server 2.5.0

package/dist/spec_loader.d.ts

@@ -0,0 +1,110 @@
+export interface ComponentMetadata {
+    description: string;
+    aliases: string[];
+    platforms: {
+        swift_generated: boolean;
+        swift_dynamic: boolean;
+        kotlin_generated: boolean;
+        kotlin_dynamic: boolean;
+        react: boolean;
+    };
+    platformSpecific: Record<string, Record<string, string>>;
+    rules: string[];
+}
+export interface ComponentSpec {
+    name: string;
+    description: string;
+    aliases: string[];
+    platforms: Record<string, boolean>;
+    attributes: Record<string, any>;
+    bindingBehavior: Record<string, any>;
+    platformSpecific: Record<string, any>;
+    rules: string[];
+}
+export type FallbackLayer = "env" | "cwd" | "home" | "bundled";
+export interface FileInfo {
+    /** Which fallback layer provided the file. */
+    layer: FallbackLayer;
+    /** Absolute path actually loaded. */
+    path: string;
+    /** ISO 8601 mtime. */
+    lastModified: string;
+    /** Freshness bucket. "fresh" <= 30d, "aging" <= 90d, "stale" > 90d. */
+    freshness: "fresh" | "aging" | "stale";
+}
+export interface DataSourceInfo {
+    attributeDefinitions: FileInfo;
+    componentMetadata: FileInfo;
+    screenIdentity: FileInfo | null;
+    bindingSemantics: FileInfo | null;
+    attributeSemantics: FileInfo | null;
+    coverage: FileInfo | null;
+    componentCount: number;
+    commonAttributeCount: number;
+}
+/**
+ * Resolution order for each jsonui-cli data file:
+ *
+ *   1. `$JSONUI_CLI_PATH` env var (custom install / monorepo)
+ *   2. `./.jsonui-cli/` in process.cwd() (project-local)
+ *   3. `~/.jsonui-cli/` (default location of the jsonui-cli bootstrap installer)
+ *   4. `<mcp-server>/data/<file>` (bundled snapshot, populated by
+ *      `scripts/fetch-definitions.js` at npm install time)
+ *
+ * A missing higher-priority layer falls through to the next. If all four fail,
+ * the loader throws — that's a hard misconfiguration.
+ */
+export declare class SpecLoader {
+    private mcpRootDir;
+    private components;
+    private commonAttributesRaw;
+    private bindingSemantics;
+    private attributeSemantics;
+    private coverageGaps;
+    private screenIdentity;
+    private commonAttributes;
+    private aliasMap;
+    private metadata;
+    private dataSource;
+    /** When this process read the files. Data is cached in memory from then
+     *  on, so a file edited later is not what the server is serving. */
+    private loadedAt;
+    constructor(mcpRootDir: string);
+    getComponent(name: string): ComponentSpec | null;
+    getComponentWithCommon(name: string): any;
+    getAttribute(name: string): any;
+    private withImplementationGaps;
+    searchComponents(query: string): any[];
+    getModifierOrder(platform?: string): any;
+    /**
+     * The canonical screen-identity asset, or null when this checkout predates
+     * it. Served verbatim: it is a declaration, not something to restate.
+     */
+    /** ISO 8601 timestamp of when this process loaded its data files. */
+    getLoadedAt(): string;
+    /**
+     * Paths whose mtime has moved since this process read them.
+     *
+     * Compares against the mtime recorded AT LOAD, not against a wall-clock
+     * timestamp: "was this file edited after I read it" is a question about
+     * the file, and comparing a file mtime to Date.now() is a race whenever
+     * the two land in the same millisecond.
+     */
+    getChangedSinceLoad(): string[];
+    getScreenIdentity(): any;
+    getBindingRules(): any;
+    getPlatformMapping(category?: string): any;
+    listComponents(): string[];
+    getDataSource(): DataSourceInfo;
+    private load;
+    private normalizeMetadata;
+    private getMetadata;
+    private buildComponentSpec;
+    /**
+     * Resolve a jsonui-cli file through the 4-layer fallback and return FileInfo.
+     * @param cliRelPath  Path inside a jsonui-cli checkout (e.g. "shared/core/attribute_definitions.json")
+     * @param bundledRelPath  Path inside this MCP's root (e.g. "data/attribute_definitions.json")
+     */
+    private resolveFile;
+}
+export declare function mcpRootFromImportMetaUrl(url: string): string;

package/dist/spec_loader.js

@@ -0,0 +1,445 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { BINDING_RULES, MODIFIER_ORDER, PLATFORM_MAPPING, categorizeCommonAttributes, } from "./data/derived.js";
+const ALL_PLATFORMS = {
+    swift_generated: true,
+    swift_dynamic: true,
+    kotlin_generated: true,
+    kotlin_dynamic: true,
+    react: true,
+};
+const DEFAULT_METADATA = {
+    description: "",
+    aliases: [],
+    platforms: ALL_PLATFORMS,
+    platformSpecific: {},
+    rules: [],
+};
+/**
+ * Resolution order for each jsonui-cli data file:
+ *
+ *   1. `$JSONUI_CLI_PATH` env var (custom install / monorepo)
+ *   2. `./.jsonui-cli/` in process.cwd() (project-local)
+ *   3. `~/.jsonui-cli/` (default location of the jsonui-cli bootstrap installer)
+ *   4. `<mcp-server>/data/<file>` (bundled snapshot, populated by
+ *      `scripts/fetch-definitions.js` at npm install time)
+ *
+ * A missing higher-priority layer falls through to the next. If all four fail,
+ * the loader throws — that's a hard misconfiguration.
+ */
+export class SpecLoader {
+    mcpRootDir;
+    components = new Map();
+    commonAttributesRaw = {};
+    bindingSemantics = null;
+    attributeSemantics = null;
+    /// `${component}.${attribute}` -> [{platform, reason, note}] from the
+    /// coverage ledger. The ledger tracks pairs that ARE declared (platform
+    /// field includes them) but that the platform's codegen does not consume —
+    /// the note explains why (backlog, alias normalization, runtime-only, ...).
+    coverageGaps = null;
+    screenIdentity = null;
+    commonAttributes = null;
+    aliasMap = new Map();
+    metadata = {};
+    dataSource;
+    /** When this process read the files. Data is cached in memory from then
+     *  on, so a file edited later is not what the server is serving. */
+    loadedAt = new Date().toISOString();
+    constructor(mcpRootDir) {
+        this.mcpRootDir = mcpRootDir;
+        this.load();
+    }
+    // ----- public API ------------------------------------------------------
+    getComponent(name) {
+        const key = name.toLowerCase();
+        const resolved = this.aliasMap.get(key) || key;
+        return this.components.get(resolved) || null;
+    }
+    getComponentWithCommon(name) {
+        const comp = this.getComponent(name);
+        if (!comp)
+            return null;
+        return { ...comp, commonAttributes: this.commonAttributes };
+    }
+    getAttribute(name) {
+        if (this.commonAttributes?.categories) {
+            for (const [category, attrs] of Object.entries(this.commonAttributes.categories)) {
+                const attrMap = attrs;
+                if (attrMap[name]) {
+                    return this.withImplementationGaps(`common.${name}`, {
+                        name,
+                        category,
+                        scope: "common",
+                        definition: attrMap[name],
+                        components: "all",
+                    });
+                }
+            }
+        }
+        const results = [];
+        for (const comp of this.components.values()) {
+            if (comp.attributes[name]) {
+                results.push(this.withImplementationGaps(`${comp.name}.${name}`, {
+                    name,
+                    scope: "component",
+                    component: comp.name,
+                    definition: comp.attributes[name],
+                    bindingBehavior: comp.bindingBehavior?.[name],
+                }));
+            }
+        }
+        if (results.length === 1)
+            return results[0];
+        if (results.length > 1)
+            return { name, matches: results };
+        return null;
+    }
+    /// Attach the coverage ledger's record for this (component, attribute) when
+    /// one exists: platforms that DECLARE the attribute but whose codegen does
+    /// not consume it, each with the recorded reason. Complements the
+    /// definition's own `platform` (declared surface) and `platform_reasons`
+    /// (why a platform is excluded from the declaration).
+    withImplementationGaps(key, result) {
+        const gaps = this.coverageGaps?.get(key);
+        if (gaps && gaps.length > 0) {
+            return { ...result, implementationGaps: gaps };
+        }
+        return result;
+    }
+    searchComponents(query) {
+        const q = query.toLowerCase();
+        const results = [];
+        for (const comp of this.components.values()) {
+            let score = 0;
+            const matches = [];
+            if (comp.name.toLowerCase().includes(q)) {
+                score += 10;
+                matches.push(`name: ${comp.name}`);
+            }
+            if (comp.description.toLowerCase().includes(q)) {
+                score += 5;
+                matches.push(`description: ${comp.description}`);
+            }
+            for (const alias of comp.aliases) {
+                if (alias.toLowerCase().includes(q)) {
+                    score += 8;
+                    matches.push(`alias: ${alias}`);
+                }
+            }
+            for (const attrName of Object.keys(comp.attributes)) {
+                if (attrName.toLowerCase().includes(q)) {
+                    score += 3;
+                    matches.push(`attribute: ${attrName}`);
+                }
+            }
+            for (const rule of comp.rules) {
+                if (rule.toLowerCase().includes(q)) {
+                    score += 2;
+                    matches.push(`rule: ${rule}`);
+                }
+            }
+            if (score > 0)
+                results.push({ component: comp.name, score, matches });
+        }
+        if (this.commonAttributes?.categories) {
+            for (const [category, attrs] of Object.entries(this.commonAttributes.categories)) {
+                const attrMap = attrs;
+                for (const [attrName, attrDef] of Object.entries(attrMap)) {
+                    if (attrName.toLowerCase().includes(q) ||
+                        attrDef?.description?.toLowerCase().includes(q)) {
+                        results.push({
+                            component: "common",
+                            score: 4,
+                            matches: [`common.${category}.${attrName}`],
+                        });
+                    }
+                }
+            }
+        }
+        return results.sort((a, b) => b.score - a.score);
+    }
+    getModifierOrder(platform) {
+        if (platform)
+            return MODIFIER_ORDER[platform] || null;
+        return MODIFIER_ORDER;
+    }
+    /**
+     * The canonical screen-identity asset, or null when this checkout predates
+     * it. Served verbatim: it is a declaration, not something to restate.
+     */
+    /** ISO 8601 timestamp of when this process loaded its data files. */
+    getLoadedAt() {
+        return this.loadedAt;
+    }
+    /**
+     * Paths whose mtime has moved since this process read them.
+     *
+     * Compares against the mtime recorded AT LOAD, not against a wall-clock
+     * timestamp: "was this file edited after I read it" is a question about
+     * the file, and comparing a file mtime to Date.now() is a race whenever
+     * the two land in the same millisecond.
+     */
+    getChangedSinceLoad() {
+        const tracked = [
+            this.dataSource.attributeDefinitions,
+            this.dataSource.componentMetadata,
+            this.dataSource.screenIdentity,
+            this.dataSource.bindingSemantics,
+            this.dataSource.attributeSemantics,
+            this.dataSource.coverage,
+        ].filter((f) => f != null);
+        const changed = [];
+        for (const file of tracked) {
+            try {
+                const now = statSync(file.path).mtime.toISOString();
+                if (now !== file.lastModified)
+                    changed.push(file.path);
+            }
+            catch {
+                // Disappeared since load — also a reason to restart.
+                changed.push(file.path);
+            }
+        }
+        return changed;
+    }
+    getScreenIdentity() {
+        return this.screenIdentity;
+    }
+    getBindingRules() {
+        // BINDING_RULES carries the author-facing syntax guidance; the
+        // canonical resolution SEMANTICS (dot paths, `??` defaults,
+        // unresolved-key behavior, negation, coercion — SSoT:
+        // shared/core/binding_semantics.json) is attached when available so
+        // the MCP never re-states semantics by hand again.
+        if (!this.bindingSemantics)
+            return BINDING_RULES;
+        return {
+            ...BINDING_RULES,
+            semanticsVersion: this.bindingSemantics.version,
+            semantics: this.bindingSemantics,
+        };
+    }
+    getPlatformMapping(category) {
+        if (category)
+            return PLATFORM_MAPPING[category] || null;
+        return PLATFORM_MAPPING;
+    }
+    listComponents() {
+        return Array.from(this.components.values()).map((c) => c.name);
+    }
+    getDataSource() {
+        return this.dataSource;
+    }
+    // ----- load pipeline ---------------------------------------------------
+    load() {
+        const attrResolution = this.resolveFile("shared/core/attribute_definitions.json", "data/attribute_definitions.json");
+        const metaResolution = this.resolveFile("shared/core/component_metadata.json", "data/component_metadata.json");
+        const raw = JSON.parse(readFileSync(attrResolution.path, "utf-8"));
+        const metaRaw = JSON.parse(readFileSync(metaResolution.path, "utf-8"));
+        let bindingResolution = null;
+        let screenIdentityResolution = null;
+        // Canonical binding-resolution semantics (renderer SSoT track 15).
+        // Optional so older jsonui-cli checkouts without the file still load.
+        try {
+            const semanticsResolution = this.resolveFile("shared/core/binding_semantics.json", "data/binding_semantics.json");
+            this.bindingSemantics = JSON.parse(readFileSync(semanticsResolution.path, "utf-8"));
+            bindingResolution = semanticsResolution;
+        }
+        catch {
+            this.bindingSemantics = null;
+        }
+        // Adjudicated attribute-semantics contract (cross-effect, plan 33).
+        // Optional for the same backward-compat reason.
+        let attributeSemanticsResolution = null;
+        try {
+            const attrSemResolution = this.resolveFile("shared/core/attribute_semantics.json", "data/attribute_semantics.json");
+            this.attributeSemantics = JSON.parse(readFileSync(attrSemResolution.path, "utf-8"));
+            attributeSemanticsResolution = attrSemResolution;
+        }
+        catch {
+            this.attributeSemantics = null;
+        }
+        // Canonical screen identity (screen-identity track). Optional so older
+        // jsonui-cli checkouts without the file still load.
+        try {
+            const screenResolution = this.resolveFile("shared/core/screen_identity.json", "data/screen_identity.json");
+            this.screenIdentity = JSON.parse(readFileSync(screenResolution.path, "utf-8"));
+            screenIdentityResolution = screenResolution;
+        }
+        catch {
+            this.screenIdentity = null;
+        }
+        // Conformance coverage ledger: declared-but-unimplemented pairs with
+        // recorded reasons. Optional for the same backward-compat reason.
+        let coverageResolution = null;
+        try {
+            const coverage = this.resolveFile("conformance/coverage.json", "data/coverage.json");
+            const doc = JSON.parse(readFileSync(coverage.path, "utf-8"));
+            const gaps = new Map();
+            for (const entry of doc.entries ?? []) {
+                const key = `${entry.component}.${entry.attribute}`;
+                const list = gaps.get(key) ?? [];
+                for (const platform of entry.platforms ?? []) {
+                    list.push({
+                        platform,
+                        reason: entry.reason ?? "",
+                        note: entry.note ?? "",
+                    });
+                }
+                gaps.set(key, list);
+            }
+            this.coverageGaps = gaps;
+            coverageResolution = coverage;
+        }
+        catch {
+            this.coverageGaps = null;
+        }
+        this.metadata = {};
+        for (const [name, meta] of Object.entries(metaRaw)) {
+            if (name.startsWith("_"))
+                continue;
+            if (typeof meta !== "object" || meta === null)
+                continue;
+            this.metadata[name] = this.normalizeMetadata(meta);
+        }
+        this.commonAttributesRaw = raw.common || {};
+        this.commonAttributes = categorizeCommonAttributes(this.commonAttributesRaw);
+        let componentCount = 0;
+        for (const [compName, compAttrs] of Object.entries(raw)) {
+            if (compName.startsWith("_") || compName === "common")
+                continue;
+            if (typeof compAttrs !== "object" || compAttrs === null)
+                continue;
+            // Component alias (`_alias_of` pointer section, jsonui-cli B1): the
+            // section carries no attribute copies — register the spelling as an
+            // alias of the canonical component instead of building an empty
+            // ComponentSpec (Toggle -> Switch is NOT covered by the metadata
+            // aliases array, so this is the only route for it).
+            const aliasOf = compAttrs["_alias_of"];
+            if (typeof aliasOf === "string" && aliasOf.length > 0) {
+                this.aliasMap.set(compName.toLowerCase(), aliasOf.toLowerCase());
+                continue;
+            }
+            const spec = this.buildComponentSpec(compName, compAttrs);
+            const key = compName.toLowerCase();
+            this.components.set(key, spec);
+            for (const alias of spec.aliases) {
+                this.aliasMap.set(alias.toLowerCase(), key);
+            }
+            componentCount++;
+        }
+        this.dataSource = {
+            attributeDefinitions: attrResolution,
+            componentMetadata: metaResolution,
+            screenIdentity: screenIdentityResolution,
+            bindingSemantics: bindingResolution,
+            attributeSemantics: attributeSemanticsResolution,
+            coverage: coverageResolution,
+            componentCount,
+            commonAttributeCount: Object.keys(this.commonAttributesRaw).filter((k) => !k.startsWith("_")).length,
+        };
+    }
+    normalizeMetadata(raw) {
+        return {
+            description: raw.description ?? "",
+            aliases: Array.isArray(raw.aliases) ? raw.aliases : [],
+            platforms: {
+                ...ALL_PLATFORMS,
+                ...(raw.platforms ?? {}),
+            },
+            platformSpecific: typeof raw.platformSpecific === "object" && raw.platformSpecific
+                ? raw.platformSpecific
+                : {},
+            rules: Array.isArray(raw.rules) ? raw.rules : [],
+        };
+    }
+    getMetadata(componentName) {
+        return (this.metadata[componentName] ?? {
+            ...DEFAULT_METADATA,
+            description: `${componentName} component`,
+        });
+    }
+    buildComponentSpec(name, attrs) {
+        const meta = this.getMetadata(name);
+        const attributes = {};
+        const bindingBehavior = {};
+        for (const [attrName, attrDef] of Object.entries(attrs)) {
+            if (attrName.startsWith("_"))
+                continue;
+            attributes[attrName] = attrDef;
+            const attrType = attrDef?.type;
+            let hasBinding = false;
+            if (Array.isArray(attrType))
+                hasBinding = attrType.includes("binding");
+            else if (attrType === "binding")
+                hasBinding = true;
+            if (hasBinding) {
+                const declared = attrDef?.binding_direction;
+                bindingBehavior[attrName] = {
+                    direction: declared === "two-way" ? "two-way" : "read-only",
+                };
+            }
+        }
+        return {
+            name,
+            description: meta.description || `${name} component`,
+            aliases: meta.aliases,
+            platforms: meta.platforms,
+            attributes,
+            bindingBehavior,
+            platformSpecific: meta.platformSpecific,
+            rules: meta.rules,
+        };
+    }
+    /**
+     * Resolve a jsonui-cli file through the 4-layer fallback and return FileInfo.
+     * @param cliRelPath  Path inside a jsonui-cli checkout (e.g. "shared/core/attribute_definitions.json")
+     * @param bundledRelPath  Path inside this MCP's root (e.g. "data/attribute_definitions.json")
+     */
+    resolveFile(cliRelPath, bundledRelPath) {
+        const candidates = [];
+        const env = process.env.JSONUI_CLI_PATH;
+        if (env) {
+            candidates.push({ path: join(resolve(env), cliRelPath), layer: "env" });
+        }
+        candidates.push({
+            path: join(process.cwd(), ".jsonui-cli", cliRelPath),
+            layer: "cwd",
+        });
+        candidates.push({
+            path: join(homedir(), ".jsonui-cli", cliRelPath),
+            layer: "home",
+        });
+        candidates.push({
+            path: join(this.mcpRootDir, bundledRelPath),
+            layer: "bundled",
+        });
+        for (const candidate of candidates) {
+            if (existsSync(candidate.path)) {
+                const mtime = statSync(candidate.path).mtime;
+                const ageDays = (Date.now() - mtime.getTime()) / (1000 * 60 * 60 * 24);
+                const freshness = ageDays <= 30 ? "fresh" : ageDays <= 90 ? "aging" : "stale";
+                return {
+                    layer: candidate.layer,
+                    path: candidate.path,
+                    lastModified: mtime.toISOString(),
+                    freshness,
+                };
+            }
+        }
+        const tried = candidates.map((c) => `  [${c.layer}] ${c.path}`).join("\n");
+        throw new Error(`jsonui-cli file not found: ${cliRelPath}. Tried:\n` +
+            tried +
+            "\n\nInstall jsonui-cli (the bootstrap places files under ~/.jsonui-cli/),\n" +
+            "or set JSONUI_CLI_PATH to point at a jsonui-cli checkout,\n" +
+            "or reinstall jsonui-mcp-server so the postinstall script can fetch a bundled snapshot.");
+    }
+}
+// Helper to derive the MCP server root from an import.meta.url (e.g. in index.ts).
+export function mcpRootFromImportMetaUrl(url) {
+    const dir = fileURLToPath(new URL(".", url));
+    return resolve(dir, "..");
+}

package/dist/tools/api/list_api_models.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+/**
+ * Discovery wrapper around `jui ls api-models --json`.
+ *
+ * Lists generated DTO + Domain scaffold files per platform, plus orphan
+ * DTOs whose source schema no longer exists in the current swagger.
+ * Agents use this to verify project state before / after `jui build`.
+ */
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/api/list_api_models.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { runCli } from "../../cli_runner.js";
+/**
+ * Discovery wrapper around `jui ls api-models --json`.
+ *
+ * Lists generated DTO + Domain scaffold files per platform, plus orphan
+ * DTOs whose source schema no longer exists in the current swagger.
+ * Agents use this to verify project state before / after `jui build`.
+ */
+export function register(server, config) {
+    server.tool("list_api_models", "List generated DTO + Domain scaffold files per platform with orphan detection", {
+        platform: z.enum(["ios", "android", "web"]).optional()
+            .describe("Restrict to a single platform"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async ({ platform, project_dir }) => {
+        try {
+            const projectDir = config.resolveProjectDir(project_dir);
+            const args = ["ls", "api-models", "--json"];
+            if (platform) {
+                args.push("--platform", platform);
+            }
+            const result = await runCli("jui", args, { cwd: projectDir });
+            if (result.exitCode !== 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: result.stderr || result.stdout || "jui ls api-models failed",
+                        }],
+                };
+            }
+            return { content: [{ type: "text", text: result.stdout.trim() }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/api/list_api_specs.d.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+/**
+ * Discovery wrapper around `jui ls api-specs --json`.
+ *
+ * Lists swagger / OpenAPI files under the project's `api_directory` with
+ * lightweight parsed metadata (title, version, schema_count, enum_count,
+ * endpoint_count) plus advisory flags for polymorphism / multi-file ref
+ * usage (`has_one_of`, `has_multi_file_ref`).
+ *
+ * Note: `has_one_of: true` is **not** equivalent to "will halt". Field-level
+ * `oneOf` paired with `discriminator` + explicit `mapping` (variants `$ref`
+ * top-level schemas + sibling discriminator property present) is supported
+ * and emits Swift enum / Kotlin sealed class / TS discriminated union code.
+ * Other shapes (anyOf, schema-level oneOf, oneOf without discriminator,
+ * discriminator alone) still halt. Agents should verify each `oneOf` site
+ * rather than blanket-flagging the file as broken.
+ */
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/api/list_api_specs.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { runCli } from "../../cli_runner.js";
+/**
+ * Discovery wrapper around `jui ls api-specs --json`.
+ *
+ * Lists swagger / OpenAPI files under the project's `api_directory` with
+ * lightweight parsed metadata (title, version, schema_count, enum_count,
+ * endpoint_count) plus advisory flags for polymorphism / multi-file ref
+ * usage (`has_one_of`, `has_multi_file_ref`).
+ *
+ * Note: `has_one_of: true` is **not** equivalent to "will halt". Field-level
+ * `oneOf` paired with `discriminator` + explicit `mapping` (variants `$ref`
+ * top-level schemas + sibling discriminator property present) is supported
+ * and emits Swift enum / Kotlin sealed class / TS discriminated union code.
+ * Other shapes (anyOf, schema-level oneOf, oneOf without discriminator,
+ * discriminator alone) still halt. Agents should verify each `oneOf` site
+ * rather than blanket-flagging the file as broken.
+ */
+export function register(server, config) {
+    server.tool("list_api_specs", "List swagger / OpenAPI files under api_directory with parsed metadata (title, version, schema/enum/endpoint counts, advisory polymorphism flags — see has_one_of caveat in tool doc)", {
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async ({ project_dir }) => {
+        try {
+            const projectDir = config.resolveProjectDir(project_dir);
+            const result = await runCli("jui", ["ls", "api-specs", "--json"], { cwd: projectDir });
+            if (result.exitCode !== 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: result.stderr || result.stdout || "jui ls api-specs failed",
+                        }],
+                };
+            }
+            // The CLI already emits a JSON document — pass it through verbatim
+            // so callers don't have to peel a wrapper envelope.
+            return { content: [{ type: "text", text: result.stdout.trim() }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/api/preview_api_model_sync.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+/**
+ * Discovery wrapper around `jui g api --dry-run --json`.
+ *
+ * Returns the schema filter result + the file list that *would* be written
+ * for each platform, without touching disk. Agents call this after a
+ * filter config change to confirm which schemas survive before running
+ * `jui build` (which would actually emit + orphan-prune).
+ */
+export declare function register(server: McpServer, config: ServerConfig): void;