jui-tools-mcp-server 2.7.0 → 2.10.0

package/src/spec_loader.ts

@@ -61,6 +61,10 @@ export interface DataSourceInfo {
   /// contract (cross-effect rulings, plan 33). Optional: absent on older
   /// jsonui-cli checkouts.
   attributeSemantics: FileInfo | null;
+  /// shared/core/platform_semantics.json — platform-scoped layout semantics
+  /// (the node-level 'platform' directive, root 'platforms', vs
+  /// 'responsive'). Optional: absent on older jsonui-cli checkouts.
+  platformSemantics: FileInfo | null;
   /// conformance/coverage.json — declared-but-unimplemented (component,
   /// attribute, platform) pairs with their recorded reasons. Optional: absent
   /// on older jsonui-cli checkouts.
@@ -102,6 +106,7 @@ export class SpecLoader {
   private commonAttributesRaw: Record<string, any> = {};
   private bindingSemantics: Record<string, any> | null = null;
   private attributeSemantics: Record<string, any> | null = null;
+  private platformSemantics: Record<string, any> | null = 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 —
@@ -243,9 +248,56 @@ export class SpecLoader {
       }
     }
 
+    // Topic-guide index: task vocabulary ("iOSだけ色を変える", "ios only",
+    // "platform override") does not contain any component or attribute
+    // name, so the loops above can't surface the mechanism. Each guide
+    // declares its own keywords (en + ja) in its semantics file; a hit
+    // pins a pointer to the dedicated tool at the top of the results.
+    for (const guide of this.topicGuides()) {
+      const hit = guide.keywords.some(
+        (kw) => q.includes(kw) || (q.length >= 3 && kw.includes(q))
+      );
+      if (hit) {
+        results.push({
+          guide: guide.topic,
+          score: 100,
+          matches: [guide.summary],
+          nextTool: guide.tool,
+        });
+      }
+    }
+
     return results.sort((a, b) => b.score - a.score);
   }
 
+  /** Keyword-indexed topical guides, each backed by a dedicated MCP tool. */
+  private topicGuides(): Array<{
+    topic: string;
+    tool: string;
+    summary: string;
+    keywords: string[];
+  }> {
+    const guides: Array<{
+      topic: string;
+      tool: string;
+      summary: string;
+      keywords: string[];
+    }> = [];
+    if (this.platformSemantics) {
+      const kws = Array.isArray(this.platformSemantics.keywords)
+        ? (this.platformSemantics.keywords as string[])
+        : [];
+      guides.push({
+        topic: "platform_rules",
+        tool: "get_platform_rules",
+        summary:
+          "Per-platform styling/visibility (e.g. change fontColor on iOS only): node-level 'platform' directive (object form = per-platform overrides, string form = platform filter), root 'platforms' whitelist, vs 'responsive'. Call get_platform_rules for the full semantics with examples.",
+        keywords: kws.map((k) => k.toLowerCase()),
+      });
+    }
+    return guides;
+  }
+
   getModifierOrder(platform?: string): any {
     if (platform) return (MODIFIER_ORDER as any)[platform] || null;
     return MODIFIER_ORDER;
@@ -275,6 +327,7 @@ export class SpecLoader {
       this.dataSource.screenIdentity,
       this.dataSource.bindingSemantics,
       this.dataSource.attributeSemantics,
+      this.dataSource.platformSemantics,
       this.dataSource.coverage,
     ].filter((f): f is FileInfo => f != null);
 
@@ -309,6 +362,15 @@ export class SpecLoader {
     };
   }
 
+  getPlatformRules(): any {
+    // Canonical platform-scoping semantics (SSoT:
+    // shared/core/platform_semantics.json — restates
+    // jui_tools/jui_cli/core/platform_resolver.py). Null on jsonui-cli
+    // checkouts that predate the file; the tool reports that instead of
+    // inventing rules.
+    return this.platformSemantics;
+  }
+
   getPlatformMapping(category?: string): any {
     if (category) return (PLATFORM_MAPPING as any)[category] || null;
     return PLATFORM_MAPPING;
@@ -376,6 +438,23 @@ export class SpecLoader {
       this.attributeSemantics = null;
     }
 
+    // Platform-scoped layout semantics (node 'platform' directive, root
+    // 'platforms', vs 'responsive'). Optional for the same backward-compat
+    // reason.
+    let platformSemanticsResolution: FileInfo | null = null;
+    try {
+      const platSemResolution = this.resolveFile(
+        "shared/core/platform_semantics.json",
+        "data/platform_semantics.json"
+      );
+      this.platformSemantics = JSON.parse(
+        readFileSync(platSemResolution.path, "utf-8")
+      ) as Record<string, any>;
+      platformSemanticsResolution = platSemResolution;
+    } catch {
+      this.platformSemantics = null;
+    }
+
     // Canonical screen identity (screen-identity track). Optional so older
     // jsonui-cli checkouts without the file still load.
     try {
@@ -462,6 +541,7 @@ export class SpecLoader {
       screenIdentity: screenIdentityResolution,
       bindingSemantics: bindingResolution,
       attributeSemantics: attributeSemanticsResolution,
+      platformSemantics: platformSemanticsResolution,
       coverage: coverageResolution,
       componentCount,
       commonAttributeCount: Object.keys(this.commonAttributesRaw).filter(

package/src/tools/context/list_screen_specs.ts

@@ -22,20 +22,38 @@ export function register(server: McpServer, config: ServerConfig) {
         }
 
         const files = readdirSync(specDir).filter((f) => f.endsWith(".spec.json"));
-        const specs = files.map((file) => {
+        const specs: any[] = [];
+        for (const file of files) {
           try {
             const data = JSON.parse(readFileSync(join(specDir, file), "utf-8"));
-            return {
+            specs.push({
               file,
               name: data.metadata?.name || file.replace(".spec.json", ""),
               displayName: data.metadata?.displayName || "",
               type: data.type || "screen_spec",
               layoutFile: data.metadata?.layoutFile || null,
-            };
+            });
+            // A parent spec splits one screen across sub-spec files (its
+            // 'subSpecs' array). Surface them inline so a session can see
+            // the split and read_spec_file the right part without first
+            // opening the parent.
+            if (Array.isArray(data.subSpecs)) {
+              for (const sub of data.subSpecs) {
+                if (!sub?.file) continue;
+                specs.push({
+                  file: sub.file,
+                  name: sub.name || sub.file,
+                  displayName: sub.description || "",
+                  type: "screen_sub_spec",
+                  parent: file,
+                  layoutFile: data.metadata?.layoutFile || null,
+                });
+              }
+            }
           } catch {
-            return { file, name: file.replace(".spec.json", ""), displayName: "", type: "unknown", layoutFile: null };
+            specs.push({ file, name: file.replace(".spec.json", ""), displayName: "", type: "unknown", layoutFile: null });
           }
-        });
+        }
 
         return { content: [{ type: "text", text: JSON.stringify(specs, null, 2) }] };
       } catch (e: any) {

package/src/tools/context/search_specs.ts

@@ -0,0 +1,124 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join, relative } from "path";
+import { ServerConfig } from "../../config.js";
+
+const MAX_RESULTS = 30;
+const SNIPPET_LEN = 200;
+
+/** Recursively collect *.spec.json / *.component.json under dir. */
+function collectSpecFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) {
+      collectSpecFiles(p, out);
+    } else if (entry.endsWith(".spec.json") || entry.endsWith(".component.json")) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk a parsed spec and report the JSON paths whose keys or string values
+ * contain the query. One entry per path, with a short snippet.
+ */
+function findMatches(
+  node: any,
+  q: string,
+  path: string,
+  out: { path: string; snippet: string }[]
+) {
+  if (out.length >= MAX_RESULTS) return;
+  if (typeof node === "string") {
+    if (node.toLowerCase().includes(q)) {
+      out.push({ path, snippet: node.slice(0, SNIPPET_LEN) });
+    }
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => findMatches(v, q, `${path}[${i}]`, out));
+    return;
+  }
+  if (node && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      const childPath = path ? `${path}.${k}` : k;
+      if (k.toLowerCase().includes(q)) {
+        const snippet =
+          typeof v === "string"
+            ? v.slice(0, SNIPPET_LEN)
+            : JSON.stringify(v)?.slice(0, SNIPPET_LEN) ?? "";
+        out.push({ path: childPath, snippet });
+        if (out.length >= MAX_RESULTS) return;
+      }
+      findMatches(v, q, childPath, out);
+      if (out.length >= MAX_RESULTS) return;
+    }
+  }
+}
+
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "search_specs",
+    "Keyword-search across ALL project spec files (screen specs, sub-specs in subdirectories, component specs). Returns file + JSON path + snippet per match — the fast way to find which spec (or which sub-spec of a split screen) covers a topic",
+    {
+      query: z.string().describe("Search keyword (matched case-insensitively against keys and string values)"),
+      project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    },
+    async ({ query, project_dir }) => {
+      try {
+        const projectDir = config.resolveProjectDir(project_dir);
+        const projectConfig = config.readProjectConfig(projectDir);
+        const q = query.toLowerCase();
+        if (!q.trim()) {
+          return { content: [{ type: "text", text: "Empty query." }] };
+        }
+
+        const dirs = new Set<string>();
+        for (const field of ["spec_directory", "component_spec_directory"] as const) {
+          try {
+            const d = config.resolveDir(projectConfig, field, projectDir);
+            if (existsSync(d)) dirs.add(d);
+          } catch {
+            /* directory not configured */
+          }
+        }
+        if (dirs.size === 0) {
+          return { content: [{ type: "text", text: "No spec directories found." }] };
+        }
+
+        const results: any[] = [];
+        for (const dir of dirs) {
+          for (const filePath of collectSpecFiles(dir)) {
+            if (results.length >= MAX_RESULTS) break;
+            let matches: { path: string; snippet: string }[] = [];
+            try {
+              const data = JSON.parse(readFileSync(filePath, "utf-8"));
+              findMatches(data, q, "", matches);
+            } catch {
+              continue;
+            }
+            if (matches.length > 0) {
+              results.push({
+                file: relative(dir, filePath),
+                matchCount: matches.length,
+                matches: matches.slice(0, 5),
+              });
+            }
+          }
+        }
+
+        if (results.length === 0) {
+          return { content: [{ type: "text", text: `No matches for '${query}'.` }] };
+        }
+        results.sort((a, b) => b.matchCount - a.matchCount);
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/doc/doc_validate_spec.ts

@@ -7,7 +7,7 @@ import { runCli } from "../../cli_runner.js";
 export function register(server: McpServer, config: ServerConfig) {
   server.tool(
     "doc_validate_spec",
-    "Validate a screen specification JSON file against the schema",
+    "Validate a screen specification JSON file against the schema. Also expands `@canonical` marks in dataFlow method params/returnType against the project's OpenAPI documents, so a mark that names no operation is reported here as an error rather than reaching `jui build`.",
     {
       file: z.string().describe("Spec file path (e.g., 'login.spec.json' or full path)"),
       project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),

package/src/tools/spec/get_platform_rules.ts

@@ -0,0 +1,26 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SpecLoader } from "../../spec_loader.js";
+
+export function register(server: McpServer, loader: SpecLoader) {
+  server.tool(
+    "get_platform_rules",
+    "Get platform-scoping rules for layouts: how to change an attribute on one platform only (node-level 'platform' object form, e.g. iOS-only fontColor), how to drop a node per platform (string form + language tokens), the layout-root 'platforms' whitelist, precedence, and how this differs from 'responsive'",
+    {},
+    async () => {
+      const result = loader.getPlatformRules();
+      if (!result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "platform_semantics.json not found — the connected jsonui-cli checkout predates it. Fall back to lookup_attribute('platform') for the short definition.",
+            },
+          ],
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+}

package/src/tools/test/test_generate_branch_tests.ts

@@ -0,0 +1,72 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ServerConfig } from "../../config.js";
+import { runCli, formatResult } from "../../cli_runner.js";
+
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "test_generate_branch_tests",
+    "Generate unit-level branch tests from a screen spec's branchContracts " +
+      "(vitest / Kotlin JUnit4+Robolectric / Swift XCTest). Only the HTTP " +
+      "boundary is mocked — ViewModel, UseCase, Repository and response " +
+      "decoding all run for real. The generated test file and runtime are " +
+      "@generated; the harness skeleton is emitted once and then owned by " +
+      "the project. Screens with no branchContracts section are an error, " +
+      "not a no-op",
+    {
+      screen: z
+        .string()
+        .describe("Screen name in snake_case (resolves <spec_directory>/<screen>.spec.json)"),
+      platform: z
+        .enum(["web", "android", "ios"])
+        .optional()
+        .describe(
+          "Target platform (default web). android additionally requires " +
+            "`package`; ios additionally requires `module`"
+        ),
+      package: z
+        .string()
+        .optional()
+        .describe("Kotlin package for the generated sources — required for platform 'android'"),
+      module: z
+        .string()
+        .optional()
+        .describe("App module name for @testable import — required for platform 'ios'"),
+      spec: z
+        .string()
+        .optional()
+        .describe("Explicit spec file path (overrides spec_directory resolution)"),
+      out_dir: z
+        .string()
+        .optional()
+        .describe("Output directory for the @generated test + runtime files"),
+      harness_dir: z
+        .string()
+        .optional()
+        .describe("Project-owned harness directory (skeleton written only when absent)"),
+      mocks_dir: z
+        .string()
+        .optional()
+        .describe("Directory scanned for *.mock.json scenario files"),
+      project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    },
+    async (params) => {
+      try {
+        const projectDir = config.resolveProjectDir(params.project_dir);
+        const args = ["generate", "branch-tests", params.screen];
+        if (params.platform) { args.push("--platform", params.platform); }
+        if (params.package) { args.push("--package", params.package); }
+        if (params.module) { args.push("--module", params.module); }
+        if (params.spec) { args.push("--spec", params.spec); }
+        if (params.out_dir) { args.push("--out-dir", params.out_dir); }
+        if (params.harness_dir) { args.push("--harness-dir", params.harness_dir); }
+        if (params.mocks_dir) { args.push("--mocks-dir", params.mocks_dir); }
+
+        const result = await runCli("jsonui-test", args, { cwd: projectDir });
+        return { content: [{ type: "text", text: formatResult(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/tests/snapshot_completeness.test.ts

@@ -45,6 +45,7 @@ function reportedFiles(source: DataSourceInfo) {
     source.screenIdentity,
     source.bindingSemantics,
     source.attributeSemantics,
+    source.platformSemantics,
     source.coverage,
   ].filter((f): f is NonNullable<typeof f> => f != null);
 }

package/tests/spec_loader.test.ts

@@ -386,6 +386,61 @@ describe("SpecLoader spec model", () => {
   });
 });
 
+describe("SpecLoader platform rules + topic-guide search", () => {
+  const SEMANTICS = {
+    version: 1,
+    title: "Platform-scoped layout semantics",
+    keywords: ["platform", "ios only", "iosだけ", "出し分け"],
+    nodeDirective: { attribute: "platform" },
+  };
+
+  function loaderWithSemantics(): SpecLoader {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    writeJson(join(mcpRoot, "data/platform_semantics.json"), SEMANTICS);
+    return new SpecLoader(mcpRoot);
+  }
+
+  it("getPlatformRules returns the semantics file verbatim", () => {
+    expect(loaderWithSemantics().getPlatformRules()).toEqual(SEMANTICS);
+  });
+
+  it("getPlatformRules is null (not invented) without the file", () => {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    expect(new SpecLoader(mcpRoot).getPlatformRules()).toBeNull();
+  });
+
+  it("task vocabulary surfaces the guide pointer at the top of search", () => {
+    // No component or attribute name in the query — only the guide can hit.
+    const results = loaderWithSemantics().searchComponents(
+      "iosだけフォントカラーを変えたい"
+    );
+    expect(results[0]).toMatchObject({
+      guide: "platform_rules",
+      nextTool: "get_platform_rules",
+      score: 100,
+    });
+  });
+
+  it("an english task query hits the guide too", () => {
+    const results = loaderWithSemantics().searchComponents("ios only color");
+    expect(results.some((r: any) => r.guide === "platform_rules")).toBe(true);
+  });
+
+  it("guide keywords do not fire on unrelated queries", () => {
+    const results = loaderWithSemantics().searchComponents("zebra");
+    expect(results.every((r: any) => r.guide == null)).toBe(true);
+  });
+
+  it("no guide entries without the semantics file", () => {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    const results = new SpecLoader(mcpRoot).searchComponents("ios only");
+    expect(results.every((r: any) => r.guide == null)).toBe(true);
+  });
+});
+
 // ----- root helper ----------------------------------------------------------
 
 describe("mcpRootFromImportMetaUrl", () => {

package/tests/tools_context.test.ts

@@ -13,6 +13,7 @@ import { register as registerListComponentSpecs } from "../src/tools/context/lis
 import { register as registerListLayouts } from "../src/tools/context/list_layouts.js";
 import { register as registerReadSpecFile } from "../src/tools/context/read_spec_file.js";
 import { register as registerReadLayoutFile } from "../src/tools/context/read_layout_file.js";
+import { register as registerSearchSpecs } from "../src/tools/context/search_specs.js";
 import {
   cleanupTempDirs,
   createToolHarness,
@@ -38,8 +39,46 @@ beforeEach(() => {
   registerListLayouts(harness.server, config);
   registerReadSpecFile(harness.server, config);
   registerReadLayoutFile(harness.server, config);
+  registerSearchSpecs(harness.server, config);
 });
 
+/** A screen split across a parent spec + sub-spec files in a subdirectory. */
+function writeSplitSpecFixture(root: string) {
+  writeJson(join(root, "docs/screens/json/messages.spec.json"), {
+    type: "screen_parent_spec",
+    metadata: {
+      name: "Messages",
+      displayName: "Messages Screen",
+      layoutFile: "messages",
+    },
+    subSpecs: [
+      {
+        file: "messages/messages-core.spec.json",
+        name: "Messages - Core",
+        description: "Core structure and message list",
+      },
+      {
+        file: "messages/messages-composer.spec.json",
+        name: "Messages - Composer",
+        description: "Input area and attachments",
+      },
+    ],
+  });
+  writeJson(join(root, "docs/screens/json/messages/messages-core.spec.json"), {
+    type: "screen_spec",
+    metadata: { name: "Messages - Core" },
+    structure: { messageList: { paging: true, currentPage: "@{currentPage}" } },
+  });
+  writeJson(
+    join(root, "docs/screens/json/messages/messages-composer.spec.json"),
+    {
+      type: "screen_spec",
+      metadata: { name: "Messages - Composer" },
+      structure: { attachButton: { note: "opens the attachment sheet" } },
+    }
+  );
+}
+
 afterEach(() => {
   delete process.env.JUI_PROJECT_DIR;
   cleanupTempDirs();
@@ -121,6 +160,81 @@ describe("list_screen_specs", () => {
     const text = await harness.call("list_screen_specs", { project_dir: proj });
     expect(text).toContain("Spec directory not found");
   });
+
+  it("expands a parent spec's subSpecs inline so the split is visible", async () => {
+    writeSplitSpecFixture(projectDir);
+    const specs = JSON.parse(
+      await harness.call("list_screen_specs", { project_dir: projectDir })
+    );
+    const core = specs.find(
+      (s: any) => s.file === "messages/messages-core.spec.json"
+    );
+    expect(core).toEqual({
+      file: "messages/messages-core.spec.json",
+      name: "Messages - Core",
+      displayName: "Core structure and message list",
+      type: "screen_sub_spec",
+      parent: "messages.spec.json",
+      layoutFile: "messages",
+    });
+    // The parent itself still lists normally.
+    expect(
+      specs.find((s: any) => s.file === "messages.spec.json")?.type
+    ).toBe("screen_parent_spec");
+  });
+});
+
+describe("search_specs", () => {
+  it("finds a keyword inside a sub-spec file in a subdirectory", async () => {
+    writeSplitSpecFixture(projectDir);
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "currentPage",
+        project_dir: projectDir,
+      })
+    );
+    const hit = results.find(
+      (r: any) => r.file === "messages/messages-core.spec.json"
+    );
+    expect(hit).toBeTruthy();
+    expect(hit.matches[0].path).toContain("structure.messageList");
+    expect(hit.matches[0].snippet).toContain("@{currentPage}");
+  });
+
+  it("matches keys as well as string values, case-insensitively", async () => {
+    writeSplitSpecFixture(projectDir);
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "ATTACHMENT",
+        project_dir: projectDir,
+      })
+    );
+    expect(
+      results.some(
+        (r: any) => r.file === "messages/messages-composer.spec.json"
+      )
+    ).toBe(true);
+  });
+
+  it("searches component specs too", async () => {
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "ExampleCard",
+        project_dir: projectDir,
+      })
+    );
+    expect(
+      results.some((r: any) => r.file === "example_card.component.json")
+    ).toBe(true);
+  });
+
+  it("reports no matches as a plain message", async () => {
+    const text = await harness.call("search_specs", {
+      query: "zzz_nothing_zzz",
+      project_dir: projectDir,
+    });
+    expect(text).toContain("No matches");
+  });
 });
 
 describe("list_component_specs", () => {