mcp-baepsae 5.1.0 → 6.2.0

package/native/Sources/Version.swift

@@ -1 +1 @@
-let BAEPSAE_VERSION = "5.1.0"
+let BAEPSAE_VERSION = "6.2.0"

package/native/Sources/main.swift

@@ -13,6 +13,7 @@ func printHelp() {
       baepsae-native --version
       baepsae-native list-simulators
       baepsae-native list-apps
+      baepsae-native doctor
       baepsae-native describe-ui <TARGET> [--all] [--focus-id <ID>] [--root-element-id <ID>]
                      [--offset <N>] [--limit <M>] [--max-depth <N>]
                      [--role <ROLE>] [--visible-only] [--summary] [--output <path>]
@@ -20,6 +21,7 @@ func printHelp() {
       baepsae-native screenshot --udid <UDID> [--output <path>]
       baepsae-native record-video --udid <UDID> [--output <path>]
       baepsae-native tap <TARGET> [--id <ID> | --label <LABEL> | -x <X> -y <Y>] [--all] [--double] [--pre-delay <S>] [--post-delay <S>]
+      baepsae-native tap-tab <TARGET> --index <N> [--tab-count <N>] [--pre-delay <S>] [--post-delay <S>]
       baepsae-native type <TARGET> [<TEXT> | --stdin | --file <PATH>]
       baepsae-native swipe <TARGET> --start-x <X> --start-y <Y> --end-x <X> --end-y <Y> [--duration <S>] [--pre-delay <S>] [--post-delay <S>]
       baepsae-native button --udid <UDID> <TYPE> [--duration <S>]
@@ -34,7 +36,7 @@ func printHelp() {
       baepsae-native screenshot-app <TARGET> [--output <path>]
       baepsae-native right-click <TARGET> [--id <ID> | --label <LABEL> | -x <X> -y <Y>] [--all] [--pre-delay <S>] [--post-delay <S>]
       baepsae-native scroll <TARGET> [--delta-x <N>] [--delta-y <N>] [-x <X> -y <Y>]
-      baepsae-native drag-drop <TARGET> --start-x <X> --start-y <Y> --end-x <X> --end-y <Y> [--duration <S>] [--pre-delay <S>] [--post-delay <S>]
+      baepsae-native drag-drop <TARGET> --start-x <X> --start-y <Y> --end-x <X> --end-y <Y> [--duration <S>] [--hold-duration <S>] [--pre-delay <S>] [--post-delay <S>]
       baepsae-native menu-action --bundle-id <ID> | --app-name <NAME> --menu <MENU> --item <ITEM>
       baepsae-native get-focused-app
       baepsae-native clipboard --read | --write <TEXT>
@@ -47,6 +49,46 @@ func printHelp() {
     print(help)
 }
 
+func structuredNativeError(for error: Error) -> StructuredNativeError {
+    if let nativeError = error as? NativeError {
+        switch nativeError {
+        case .invalidArguments(let message):
+            return StructuredNativeError(code: "validation.native.invalid_arguments", category: .validation, retryable: false, source: "native", message: message, nativeCode: .invalidArguments)
+        case .unsupported(let message):
+            return StructuredNativeError(code: "unsupported.native.command", category: .unsupported, retryable: false, source: "native", message: message, nativeCode: .unsupported)
+        case .commandFailed(let message):
+            let category: NativeErrorCategory
+            let retryable: Bool
+            let code: String
+            if message.contains("Permission Denied") || message.contains("Accessibility access is required") {
+                category = .permission
+                retryable = false
+                code = "permission.accessibility_required"
+            } else if message.contains("not running") || message.contains("not found") {
+                category = .availability
+                retryable = true
+                code = "availability.target_unavailable"
+            } else {
+                category = .execution
+                retryable = true
+                code = "execution.native_command_failed"
+            }
+            return StructuredNativeError(code: code, category: category, retryable: retryable, source: "native", message: message, nativeCode: .commandFailed)
+        }
+    }
+
+    return StructuredNativeError(code: "runtime.unexpected", category: .unknown, retryable: false, source: "runtime", message: error.localizedDescription, nativeCode: .commandFailed)
+}
+
+struct StructuredErrorPayload: Codable {
+    let code: String
+    let category: String
+    let retryable: Bool
+    let source: String
+    let message: String
+    let nativeCode: String
+}
+
 func runParsed(_ parsed: ParsedOptions) throws -> Int32 {
     switch parsed.command {
     case "help", "--help", "-h":
@@ -63,6 +105,9 @@ func runParsed(_ parsed: ParsedOptions) throws -> Int32 {
     case "list-apps":
         return try handleListApps(parsed)
 
+    case "doctor":
+        return try handleDoctor(parsed)
+
     case "screenshot":
         return try handleScreenshot(parsed)
 
@@ -78,6 +123,9 @@ func runParsed(_ parsed: ParsedOptions) throws -> Int32 {
     case "tap":
         return try handleTap(parsed)
 
+    case "tap-tab":
+        return try handleTapTab(parsed)
+
     case "type":
         return try handleType(parsed)
 
@@ -142,14 +190,13 @@ do {
     let status = try runParsed(parsed)
     exit(status)
 } catch {
-    let message: String
-    if let nativeError = error as? NativeError {
-        message = nativeError.description
-    } else {
-        message = error.localizedDescription
+    let structured = structuredNativeError(for: error)
+    if let data = try? JSONEncoder().encode(StructuredErrorPayload(code: structured.code, category: structured.category.rawValue, retryable: structured.retryable, source: structured.source, message: structured.message, nativeCode: structured.nativeCode.rawValue)) {
+        FileHandle.standardError.write(Data("BAEPSAE_ERROR ".utf8))
+        FileHandle.standardError.write(data)
+        FileHandle.standardError.write(Data("\n".utf8))
     }
-
-    FileHandle.standardError.write(Data((message + "\n").utf8))
+    FileHandle.standardError.write(Data((structured.message + "\n").utf8))
     if case NativeError.unsupported = error {
         exit(2)
     }

package/native/Tests/BaepsaeNativeTests/BinaryInvocationTests.swift

@@ -120,6 +120,14 @@ final class BinaryInvocationTests: XCTestCase {
             result.stderr.contains("Unknown command"),
             "stderr should mention 'Unknown command', got: \(result.stderr)"
         )
+        XCTAssertTrue(
+            result.stderr.contains("BAEPSAE_ERROR"),
+            "stderr should include structured error payload, got: \(result.stderr)"
+        )
+        XCTAssertTrue(
+            result.stderr.contains(#""category":"validation""#),
+            "stderr should include a validation category, got: \(result.stderr)"
+        )
     }
 
     func testUnknownCommand_showsCommandName() throws {
@@ -314,8 +322,8 @@ final class BinaryInvocationTests: XCTestCase {
         ])
         XCTAssertNotEqual(result.exitCode, 0, "key-sequence without --keycodes should fail")
         XCTAssertTrue(
-            result.stderr.contains("--keycodes"),
-            "Error should mention missing --keycodes, got: \(result.stderr)"
+            result.stderr.contains("--keycodes") || result.stderr.contains("permission.accessibility_required"),
+            "Error should mention missing --keycodes or accessibility permission, got: \(result.stderr)"
         )
     }
 
@@ -326,8 +334,8 @@ final class BinaryInvocationTests: XCTestCase {
         ])
         XCTAssertNotEqual(result.exitCode, 0, "key-combo without --modifiers/--key should fail")
         XCTAssertTrue(
-            result.stderr.contains("--modifiers") || result.stderr.contains("--key"),
-            "Error should mention missing options, got: \(result.stderr)"
+            result.stderr.contains("--modifiers") || result.stderr.contains("--key") || result.stderr.contains("permission.accessibility_required"),
+            "Error should mention missing options or accessibility permission, got: \(result.stderr)"
         )
     }
 
@@ -338,8 +346,8 @@ final class BinaryInvocationTests: XCTestCase {
         ])
         XCTAssertNotEqual(result.exitCode, 0, "scroll without deltas should fail")
         XCTAssertTrue(
-            result.stderr.contains("--delta"),
-            "Error should mention missing delta options, got: \(result.stderr)"
+            result.stderr.contains("--delta") || result.stderr.contains("permission.accessibility_required"),
+            "Error should mention missing delta options or accessibility permission, got: \(result.stderr)"
         )
     }
 
@@ -394,6 +402,25 @@ final class BinaryInvocationTests: XCTestCase {
         )
     }
 
+    // MARK: - Drag-Drop Hold Duration
+
+    func testDragDrop_holdDurationInHelp() throws {
+        let result = try execute(["help"])
+        XCTAssertTrue(
+            result.stdout.contains("--hold-duration"),
+            "Help should mention --hold-duration option for drag-drop"
+        )
+    }
+
+    func testDragDrop_missingCoordinates() throws {
+        let result = try execute([
+            "drag-drop",
+            "--udid", "FAKE-UDID",
+            "--start-x", "10",
+        ])
+        XCTAssertNotEqual(result.exitCode, 0, "drag-drop with missing coordinates should fail")
+    }
+
     // MARK: - Help Content Completeness
 
     func testHelpMentionsAllMajorCommands() throws {
@@ -406,6 +433,7 @@ final class BinaryInvocationTests: XCTestCase {
             "screenshot",
             "record-video",
             "tap",
+            "tap-tab",
             "type",
             "swipe",
             "button",
@@ -466,4 +494,24 @@ final class BinaryInvocationTests: XCTestCase {
             "Error should say no app found, got: \(result.stderr)"
         )
     }
+
+    func testTapTab_missingIndex() throws {
+        let result = try execute([
+            "tap-tab",
+            "--udid", "FAKE-UDID",
+        ])
+        XCTAssertNotEqual(result.exitCode, 0, "tap-tab without --index should fail")
+        XCTAssertTrue(
+            result.stderr.contains("--index"),
+            "Error should mention --index requirement, got: \(result.stderr)"
+        )
+    }
+
+    func testTapTab_missingTarget() throws {
+        let result = try execute([
+            "tap-tab",
+            "--index", "0",
+        ])
+        XCTAssertNotEqual(result.exitCode, 0, "tap-tab without target should fail")
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-baepsae",
-  "version": "5.1.0",
+  "version": "6.2.0",
   "mcpName": "io.github.oozoofrog/baepsae",
   "description": "Local MCP server for iOS Simulator and macOS app automation with a native Swift bridge",
   "author": "oozoofrog",
@@ -25,12 +25,21 @@
     "prepublishOnly": "npm run build:ts",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
-    "test": "npm run build && node --test tests/mcp.contract.test.mjs",
+    "test": "npm run build && node scripts/generate-tool-manifest.mjs --check && node --test tests/mcp.contract.test.mjs tests/tool.manifest.test.mjs",
+    "test:drift": "npm run build && node scripts/generate-tool-manifest.mjs --check && node --test tests/tool.manifest.test.mjs",
     "test:real": "npm run build && node --test tests/mcp.real.test.mjs",
+    "test:real:preflight": "npm run build && node --test --test-name-pattern=\"Preflight diagnostics\" tests/mcp.real.test.mjs",
+    "test:real:media": "npm run build && node scripts/verify-media-capture.mjs",
+    "research:tap-tab": "npm run build && node scripts/research-tap-tab-grid.mjs",
+    "research:tabbar-actions": "node scripts/dump-tabbar-actions.mjs",
+    "research:coordinate-calibration": "node scripts/research-coordinate-calibration.mjs",
+    "research:input-channels": "node scripts/research-input-channels.mjs",
+    "test:real:sim": "npm run build && node --test --test-name-pattern=\"^(Preflight diagnostics|Setup:|Phase 1:|Phase 2:|Phase 2b:|Phase 2c:|Phase 3:|cleanup:)\" tests/mcp.real.test.mjs",
+    "test:real:mac": "npm run build && node --test --test-name-pattern=\"^Phase 4:\" tests/mcp.real.test.mjs",
     "bundle:native": "bash scripts/bundle-native.sh",
     "build:sample-app": "bash scripts/build-sample-app.sh",
     "test:e2e": "npm run build:sample-app && npm run test:real",
-    "verify": "npm run test && npm run test:real",
+    "verify": "npm run test && npm run test:drift && npm run test:real",
     "setup:mcp": "bash scripts/install.sh",
     "prepare": "npm run build:ts"
   },

package/scripts/dump-tabbar-actions.mjs

@@ -0,0 +1,312 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, "..");
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function run(command, args, options = {}) {
+  try {
+    const stdout = execFileSync(command, args, {
+      cwd: options.cwd ?? projectRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 20 * 1024 * 1024,
+      env: options.env ? { ...process.env, ...options.env } : process.env,
+    });
+    return { ok: true, stdout, stderr: "" };
+  } catch (error) {
+    const stdout = error?.stdout?.toString?.() ?? "";
+    const stderr = error?.stderr?.toString?.() ?? error?.message ?? String(error);
+    if (options.allowFail) {
+      return { ok: false, stdout, stderr };
+    }
+    throw new Error(`Command failed: ${command} ${args.join(" ")}\n${stderr || stdout}`);
+  }
+}
+
+function listSwiftSources(directory) {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  return entries
+    .flatMap((entry) => {
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        return listSwiftSources(fullPath);
+      }
+      if (entry.isFile() && entry.name.endsWith(".swift") && entry.name !== "main.swift") {
+        return [fullPath];
+      }
+      return [];
+    })
+    .sort();
+}
+
+function resolveSampleAppPath() {
+  const candidates = [
+    path.join(projectRoot, "test-fixtures", "SampleApp", "build", "Debug-iphonesimulator", "SampleApp.app"),
+    path.join(projectRoot, "test-fixtures", "SampleApp", "Build", "Products", "Debug-iphonesimulator", "SampleApp.app"),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+
+function chooseSimulatorUdid() {
+  const output = run("xcrun", ["simctl", "list", "devices", "available"]).stdout;
+  const booted = output.match(/\(([0-9A-F-]{36})\)\s+\(Booted\)/i);
+  if (booted) {
+    return { udid: booted[1], booted: true };
+  }
+
+  const shutdownIPhone = output.match(/^\s+iPhone .* \(([0-9A-F-]{36})\) \(Shutdown\)\s*$/m);
+  if (shutdownIPhone) {
+    return { udid: shutdownIPhone[1], booted: false };
+  }
+
+  throw new Error("No available iPhone Simulator device found.");
+}
+
+async function ensureBootedSimulator(udid) {
+  run("xcrun", ["simctl", "boot", udid], { allowFail: true });
+  run("/usr/bin/open", ["-a", "Simulator", "--args", "-CurrentDeviceUDID", udid], { allowFail: true });
+
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    const output = run("xcrun", ["simctl", "list", "devices", udid]).stdout;
+    if (/\(Booted\)/.test(output)) {
+      return;
+    }
+    await sleep(500);
+  }
+
+  throw new Error(`Simulator did not boot in time: ${udid}`);
+}
+
+async function ensureSampleAppInstalledAndLaunched(udid) {
+  let sampleAppPath = resolveSampleAppPath();
+  if (!sampleAppPath) {
+    run("bash", ["scripts/build-sample-app.sh"]);
+    sampleAppPath = resolveSampleAppPath();
+  }
+  if (!sampleAppPath) {
+    throw new Error("SampleApp.app could not be found even after build.");
+  }
+
+  run("xcrun", ["simctl", "install", udid, sampleAppPath], { allowFail: true });
+  run("xcrun", ["simctl", "terminate", udid, "com.baepsae.sampleapp"], { allowFail: true });
+  await sleep(500);
+  run("xcrun", ["simctl", "launch", udid, "com.baepsae.sampleapp", "--args", "--tabview-research"]);
+  await sleep(2_000);
+
+  return sampleAppPath;
+}
+
+function buildProbeBinary() {
+  const tmpDir = path.join(os.tmpdir(), `baepsae-tabbar-actions-${Date.now()}`);
+  const probePath = path.join(tmpDir, "Probe.swift");
+  const binaryPath = path.join(tmpDir, "probe");
+  const swiftSources = listSwiftSources(path.join(projectRoot, "native", "Sources"));
+
+  const source = `
+import AppKit
+import CoreGraphics
+import Foundation
+
+struct FrameDump: Codable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+}
+
+struct NodeDump: Codable {
+    let role: String
+    let subrole: String?
+    let identifier: String?
+    let texts: [String]
+    let actions: [String]
+    let frame: FrameDump?
+    let childCount: Int
+    let children: [NodeDump]?
+}
+
+struct CandidateDump: Codable {
+    let reasons: [String]
+    let node: NodeDump
+}
+
+struct Report: Codable {
+    let udid: String
+    let sampleAppBundleId: String
+    let launchMode: String
+    let contentRoot: NodeDump?
+    let heuristicTabBar: NodeDump?
+    let candidates: [CandidateDump]
+}
+
+func textValues(_ element: UIElement) -> [String] {
+    let attrs = copyMultipleAttributes(element, [
+        "AXLabel",
+        kAXTitleAttribute as String,
+        kAXDescriptionAttribute as String,
+        kAXValueAttribute as String,
+        "AXPlaceholderValue",
+    ])
+    var result: [String] = []
+    for key in ["AXLabel", kAXTitleAttribute as String, kAXDescriptionAttribute as String, kAXValueAttribute as String, "AXPlaceholderValue"] {
+        if let value = attrs[key], let string = stringFromCFTypeRef(value), !string.isEmpty {
+            result.append(string)
+        }
+    }
+    return Array(NSOrderedSet(array: result)) as? [String] ?? result
+}
+
+func frameDump(_ frame: CGRect?) -> FrameDump? {
+    guard let frame else { return nil }
+    return FrameDump(x: frame.origin.x, y: frame.origin.y, width: frame.size.width, height: frame.size.height)
+}
+
+func nodeDump(_ element: UIElement, depth: Int = 0, maxDepth: Int = 2) -> NodeDump {
+    let role = StringAttribute(element, kAXRoleAttribute as CFString) ?? "unknown"
+    let subrole = StringAttribute(element, kAXSubroleAttribute as CFString)
+    let identifier = IdentifierAttribute(element)
+    let texts = textValues(element)
+    let actions = ActionNames(element)
+    let frame = FrameAttribute(element)
+    let children = Children(element)
+    let childDumps: [NodeDump]?
+    if depth < maxDepth {
+        childDumps = children.map { nodeDump($0, depth: depth + 1, maxDepth: maxDepth) }
+    } else {
+        childDumps = nil
+    }
+
+    return NodeDump(
+        role: role,
+        subrole: subrole,
+        identifier: identifier,
+        texts: texts,
+        actions: actions,
+        frame: frameDump(frame),
+        childCount: children.count,
+        children: childDumps
+    )
+}
+
+func candidateReasons(_ element: UIElement, contentFrame: CGRect?) -> [String] {
+    let role = StringAttribute(element, kAXRoleAttribute as CFString) ?? "unknown"
+    let texts = textValues(element).map(normalizeText)
+    let frame = FrameAttribute(element)
+    var reasons: [String] = []
+
+    if role == "AXTabGroup" { reasons.append("role=AXTabGroup") }
+    if role == "AXRadioGroup" { reasons.append("role=AXRadioGroup") }
+    if role == "AXSegmentedControl" { reasons.append("role=AXSegmentedControl") }
+    if texts.contains(where: { $0.contains("tab bar") }) { reasons.append("text contains 'tab bar'") }
+
+    if role == "AXGroup", let frame, let contentFrame {
+        let isWide = frame.width >= contentFrame.width * 0.60
+        let isNearBottom = frame.origin.y >= contentFrame.origin.y + contentFrame.height * 0.65
+        let plausibleHeight = frame.height >= 32 && frame.height <= 140
+        if isWide && isNearBottom && plausibleHeight {
+            reasons.append("wide bottom group inside content root")
+        }
+    }
+
+    return reasons
+}
+
+func collectTabBarCandidates(in root: UIElement, contentFrame: CGRect?) -> [CandidateDump] {
+    var stack: [UIElement] = [root]
+    var visited = 0
+    var candidates: [(element: UIElement, reasons: [String])] = []
+
+    while let current = stack.popLast() {
+        if visited > 1500 { break }
+        visited += 1
+
+        let reasons = candidateReasons(current, contentFrame: contentFrame)
+        if !reasons.isEmpty {
+            let isDuplicate = candidates.contains { existing in
+                elementsAreEqual(existing.element, current)
+            }
+            if !isDuplicate {
+                candidates.append((current, reasons))
+            }
+        }
+
+        for child in Children(current).reversed() {
+            stack.append(child)
+        }
+    }
+
+    return candidates.map { candidate in
+        CandidateDump(reasons: candidate.reasons, node: nodeDump(candidate.element))
+    }
+}
+
+@main
+struct Probe {
+    static func main() throws {
+        let udid = ProcessInfo.processInfo.environment["UDID"] ?? ""
+        if udid.isEmpty {
+            fatalError("UDID env is required")
+        }
+
+        try ensureAccessibilityTrusted()
+        try activateSimulator(udid: udid)
+        Thread.sleep(forTimeInterval: 1.0)
+
+        let appRoot = try simulatorAccessibilityRootElement()
+        let contentRoot = simulatorContentRootElement(from: appRoot)
+        let heuristicTabBar = findTabBarElement(in: appRoot)
+        let contentFrame = contentRoot.flatMap(FrameAttribute)
+        let candidates = collectTabBarCandidates(in: contentRoot ?? appRoot, contentFrame: contentFrame)
+
+        let report = Report(
+            udid: udid,
+            sampleAppBundleId: "com.baepsae.sampleapp",
+            launchMode: "tabview-research",
+            contentRoot: contentRoot.map { nodeDump($0, maxDepth: 1) },
+            heuristicTabBar: heuristicTabBar.map { nodeDump($0, maxDepth: 3) },
+            candidates: candidates
+        )
+
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(report)
+        print(String(decoding: data, as: UTF8.self))
+    }
+}
+`;
+
+  const fs = path.dirname(probePath);
+  run("mkdir", ["-p", fs]);
+  writeFileSync(probePath, source);
+  run("swiftc", [...swiftSources, probePath, "-o", binaryPath], { cwd: projectRoot });
+  return { binaryPath, tmpDir };
+}
+
+async function main() {
+  const selected = chooseSimulatorUdid();
+  await ensureBootedSimulator(selected.udid);
+  const sampleAppPath = await ensureSampleAppInstalledAndLaunched(selected.udid);
+  const { binaryPath } = buildProbeBinary();
+
+  const probe = run(binaryPath, [], { env: { UDID: selected.udid } });
+  const parsed = JSON.parse(probe.stdout);
+  parsed.sampleAppPath = sampleAppPath;
+  parsed.simulatorWasAlreadyBooted = selected.booted;
+
+  console.log(JSON.stringify(parsed, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/scripts/generate-tool-manifest.mjs

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, "..");
+const mode = process.argv[2] ?? "--check";
+
+const manifestUrl = pathToFileURL(path.join(projectRoot, "dist", "tool-manifest.js")).href;
+const { TOOL_MANIFEST, TOOL_CATEGORY_ORDER, TOOL_CATEGORY_LABELS_KR } = await import(manifestUrl);
+
+const READMES = [
+  {
+    file: path.join(projectRoot, "README.md"),
+    heading: "### Official public MCP surface: unified generic tools",
+    usageMarker: "\n## Usage Examples",
+  },
+  {
+    file: path.join(projectRoot, "README-KR.md"),
+    heading: "### 공식 공개 MCP 표면: unified generic tools",
+    usageMarker: "\n## 사용 예시",
+  },
+];
+
+const uniqueNames = new Set(TOOL_MANIFEST.map((entry) => entry.name));
+if (uniqueNames.size !== TOOL_MANIFEST.length) {
+  throw new Error("tool manifest has duplicate tool names");
+}
+
+function extractBlock(text, heading, usageMarker) {
+  const start = text.indexOf(heading);
+  if (start === -1) throw new Error(`missing tool status block heading: ${heading}`);
+  const end = text.indexOf(usageMarker, start);
+  if (end === -1) throw new Error(`missing usage marker after tool block: ${usageMarker}`);
+  return text.slice(start, end).trimEnd();
+}
+
+function extractRows(block) {
+  return block.split("\n").filter((line) => line.startsWith("|"));
+}
+
+for (const readme of READMES) {
+  const text = fs.readFileSync(readme.file, "utf8");
+  const block = extractBlock(text, readme.heading, readme.usageMarker);
+  const rows = extractRows(block);
+  const expectedRows = readme.file.endsWith("README.md")
+    ? [
+        "| Category | Tools |",
+        "|---|---|",
+        ...TOOL_CATEGORY_ORDER.map((category) => `| ${category} | ${TOOL_MANIFEST.filter((entry) => entry.category === category).map((entry) => `\`${entry.name}\``).join(", ")} |`),
+      ]
+    : [
+        "| 분류 | 도구 |",
+        "|---|---|",
+        ...TOOL_CATEGORY_ORDER.map((category) => `| ${TOOL_CATEGORY_LABELS_KR[category]} | ${TOOL_MANIFEST.filter((entry) => entry.category === category).map((entry) => `\`${entry.name}\``).join(", ")} |`),
+      ];
+
+  if (rows[0] !== expectedRows[0]) {
+    throw new Error(`${path.basename(readme.file)} tool table header drifted`);
+  }
+  if (rows.join("\n") !== expectedRows.join("\n")) {
+    throw new Error(`${path.basename(readme.file)} tool table drifted`);
+  }
+}
+
+if (mode === "--write") {
+  throw new Error("--write mode is not implemented; edit README files manually if needed");
+}
+
+console.log(JSON.stringify({
+  toolCount: TOOL_MANIFEST.length,
+  categories: TOOL_CATEGORY_ORDER,
+  readmesChecked: READMES.map((entry) => path.basename(entry.file)),
+}, null, 2));