react-native-mcp-kit 2.1.0 → 2.2.0

package/dist/server/mcpServer.js

@@ -12,25 +12,152 @@ Multiple React Native apps can connect simultaneously — each is identified by
 ## How to interact
 
 1. Use \`connection_status\` to check which clients are connected.
-2. Use \`list_tools\` to browse all available tool names and short descriptions. The response is compact — modules that are structurally identical across multiple clients are deduplicated into a single entry with a \`clientIds\` array, and input schemas are omitted.
+2. Use \`list_tools\` to browse all available tool names and short descriptions. The response is compact — modules that are structurally identical across multiple clients are deduplicated into a single entry with a \`clientIds\` array, and input schemas are omitted. Narrow the listing with \`{ module }\` or \`{ clientId }\`, or pass \`{ compact: true }\` to drop module-level descriptions.
 3. Use \`describe_tool\` with \`{ tool, clientId? }\` to fetch the full input schema of a specific tool before calling it. Required when you need to know the argument shape. Host tools are resolved directly (no clientId needed). For in-app tools, omit \`clientId\` to auto-pick; specify it only when multiple clients have the same tool with different schemas.
-4. Use \`call\` to invoke any tool with format: module${protocol_1.MODULE_SEPARATOR}method (e.g. navigation${protocol_1.MODULE_SEPARATOR}navigate). When more than one client is connected, specify \`clientId\`. When exactly one client is connected, \`clientId\` is optional — it's auto-picked.
-5. Use \`state_list\` / \`state_get\` to read app state exposed via useMcpState. State is scoped per client; specify \`clientId\` when multiple clients are connected.
+4. Use \`call\` to invoke any tool with format: module${protocol_1.MODULE_SEPARATOR}method (e.g. navigation${protocol_1.MODULE_SEPARATOR}navigate). When more than one client is connected, specify \`clientId\`. When exactly one client is connected, \`clientId\` is optional — it's auto-picked. \`args\` accepts either a plain object or a JSON string — prefer objects to avoid quote escaping.
+5. Use \`wait_until\` to poll any tool until a predicate over its result holds (or timeout). Replaces "screenshot in a loop + sleep" for things like "wait for screen X", "wait for the spinner to disappear", "wait for network to idle". Predicate supports compound forms: { all: [...] } (AND), { any: [...] } (OR), { not: predicate }.
+6. Use \`assert\` for a single-shot checkpoint after actions — same predicate vocabulary as wait_until, returns { pass, actual, expected?, result? }. Natural pair: do action → wait_until → assert.
+7. Use \`host${protocol_1.MODULE_SEPARATOR}tap_fiber\` to collapse "fiber_tree__query → host__tap at bounds" into one call. Pass fiber_tree steps; if exactly one fiber matches, its center is tapped. Ambiguous match returns the candidate list so you can add \`index\` or narrow the chain.
+8. Use \`state_list\` / \`state_get\` to read app state exposed via useMcpState. State is scoped per client; specify \`clientId\` when multiple clients are connected.
 
-Some tools run inline on the MCP server host (e.g. \`host${protocol_1.MODULE_SEPARATOR}screenshot\`, \`host${protocol_1.MODULE_SEPARATOR}list_devices\`, \`host${protocol_1.MODULE_SEPARATOR}launch_app\`, \`host${protocol_1.MODULE_SEPARATOR}terminate_app\`, \`host${protocol_1.MODULE_SEPARATOR}restart_app\`) and work even when no React Native client is connected. They use xcrun simctl / adb on the dev machine. When \`clientId\` is provided, host tools use that client's platform/label/deviceId as hints to resolve the target device; otherwise they prefer the device of the single connected client, falling back to the single booted sim / online device. \`launch_app\`, \`terminate_app\`, and \`restart_app\` accept an \`appId\` arg (iOS bundle ID / Android package name); omit it to reuse the target client's registered \`bundleId\` from its connection metadata.
+Some tools run inline on the MCP server host (e.g. \`host${protocol_1.MODULE_SEPARATOR}screenshot\`, \`host${protocol_1.MODULE_SEPARATOR}list_devices\`, \`host${protocol_1.MODULE_SEPARATOR}launch_app\`, \`host${protocol_1.MODULE_SEPARATOR}terminate_app\`, \`host${protocol_1.MODULE_SEPARATOR}restart_app\`, \`host${protocol_1.MODULE_SEPARATOR}symbolicate\`) and work even when no React Native client is connected. They use xcrun simctl / adb on the dev machine. When \`clientId\` is provided, host tools use that client's platform/label/deviceId as hints to resolve the target device; otherwise they prefer the device of the single connected client, falling back to the single booted sim / online device. \`launch_app\`, \`terminate_app\`, and \`restart_app\` accept an \`appId\` arg (iOS bundle ID / Android package name); omit it to reuse the target client's registered \`bundleId\` from its connection metadata.
 
 ## Driving the UI — pick the right tool
-1. **\`fiber_tree${protocol_1.MODULE_SEPARATOR}find_all\` with \`select: ["mcpId", "name", "bounds"]\` + \`host${protocol_1.MODULE_SEPARATOR}tap\` with \`bounds.centerX\`/\`bounds.centerY\`** — the default for touch interactions. Exercises the real OS gesture pipeline, so Pressable/TouchableOpacity feedback, gesture responders, and hit-test logic all run. The bounds come back in physical pixels — pass them straight to \`host${protocol_1.MODULE_SEPARATOR}tap\`, no scaling. The \`select\` parameter also saves tokens by omitting heavy \`props\` from the response.
-2. **\`fiber_tree${protocol_1.MODULE_SEPARATOR}invoke\`** when you need to bypass the gesture pipeline — e.g. for non-tap callbacks like \`onChangeText\` / \`onValueChange\` / \`onRefresh\`, or when a component is inside a scroll/gesture-handler parent that swallows taps. Calls the prop directly — faster and immune to overlay/occlusion, but does not exercise touch handlers.
-3. **\`host${protocol_1.MODULE_SEPARATOR}screenshot\` + manual coordinate estimation + \`host${protocol_1.MODULE_SEPARATOR}tap\`** ONLY for non-React surfaces: system permission dialogs, native alerts, the on-screen keyboard, WebView content, native splash. These have no fiber and no bounds.
+1. **\`host${protocol_1.MODULE_SEPARATOR}tap_fiber\` with \`steps: [...]\`** — the canonical way to simulate a user tap. One call locates the fiber via fiber_tree__query and taps its center through the real OS gesture pipeline, so Pressable feedback, gesture responders, and hit-test logic all run. Ambiguous matches return a candidate list so you can add \`index\` or narrow \`steps\`. This is what you want whenever the user asks to simulate a tap / press / button click.
+2. **\`fiber_tree${protocol_1.MODULE_SEPARATOR}query\` with \`select: ["mcpId","name","bounds"]\` + \`host${protocol_1.MODULE_SEPARATOR}tap\`** when you want to inspect a match set before committing — e.g. verify bounds, or skim candidates before picking one. \`props\` is opt-in on \`select\` to keep responses small.
+3. **\`fiber_tree${protocol_1.MODULE_SEPARATOR}invoke\`** for non-gesture callbacks — anything state-driving the user didn't trigger with a finger. Good when the component is off-screen / virtualised, when a scroll-handler parent swallows taps, or when you're specifically testing a callback in isolation without the gesture pipeline. For simulating a user tap, prefer tap_fiber (above).
+4. **\`host${protocol_1.MODULE_SEPARATOR}screenshot\` + manual coordinate estimation + \`host${protocol_1.MODULE_SEPARATOR}tap\`** ONLY for non-React surfaces: system permission dialogs, native alerts, the on-screen keyboard, WebView content, native splash. These have no fiber and no bounds. Pair with \`region: { x, y, width, height }\` to screenshot just the area you're inspecting — vision-token cheap.
 
-\`host${protocol_1.MODULE_SEPARATOR}tap\` / \`host${protocol_1.MODULE_SEPARATOR}swipe\` / \`host${protocol_1.MODULE_SEPARATOR}type_text\` / \`host${protocol_1.MODULE_SEPARATOR}press_key\` work on both platforms with no external daemons: Android via \`adb shell input\`, iOS via a bundled \`ios-hid\` binary that injects HID events directly into iOS Simulator through SimulatorKit.
+Gesture tools: \`host${protocol_1.MODULE_SEPARATOR}tap\` / \`host${protocol_1.MODULE_SEPARATOR}long_press\` / \`host${protocol_1.MODULE_SEPARATOR}swipe\` / \`host${protocol_1.MODULE_SEPARATOR}drag\` / \`host${protocol_1.MODULE_SEPARATOR}type_text\` / \`host${protocol_1.MODULE_SEPARATOR}type_text_batch\` / \`host${protocol_1.MODULE_SEPARATOR}press_key\` work on both platforms with no external daemons: Android via \`adb shell input\`, iOS via a bundled \`ios-hid\` binary that injects HID events directly into iOS Simulator through SimulatorKit.
+
+Stack traces: \`errors${protocol_1.MODULE_SEPARATOR}get_errors\` and \`log_box${protocol_1.MODULE_SEPARATOR}get_logs\` return parsed \`stackFrames\` you can pass straight into \`host${protocol_1.MODULE_SEPARATOR}symbolicate\` to resolve bundled frames back to source paths via Metro.
 `;
 const jsonError = (msg) => {
     return {
         content: [{ text: JSON.stringify({ error: msg }), type: 'text' }],
     };
 };
+/**
+ * Drill into a value by dot-path. Arrays accept numeric indices and also
+ * respond to `.length` (handy for "wait until list is empty"). Returns
+ * undefined when any intermediate segment is missing.
+ */
+const resolvePath = (value, path) => {
+    if (!path)
+        return value;
+    let current = value;
+    for (const key of path.split('.')) {
+        if (current == null)
+            return undefined;
+        if (Array.isArray(current)) {
+            if (key === 'length') {
+                current = current.length;
+                continue;
+            }
+            const idx = Number.parseInt(key, 10);
+            current = Number.isNaN(idx) ? undefined : current[idx];
+            continue;
+        }
+        if (typeof current === 'object') {
+            current = current[key];
+            continue;
+        }
+        return undefined;
+    }
+    return current;
+};
+const evalLeaf = (actual, op, expected) => {
+    switch (op) {
+        case 'exists':
+            return actual !== undefined && actual !== null;
+        case 'notExists':
+            return actual === undefined || actual === null;
+        case 'equals':
+            return Object.is(actual, expected);
+        case 'notEquals':
+            return !Object.is(actual, expected);
+        case 'contains': {
+            if (typeof actual === 'string' && typeof expected === 'string') {
+                return actual.includes(expected);
+            }
+            if (Array.isArray(actual))
+                return actual.includes(expected);
+            return false;
+        }
+        case 'notContains': {
+            if (typeof actual === 'string' && typeof expected === 'string') {
+                return !actual.includes(expected);
+            }
+            if (Array.isArray(actual))
+                return !actual.includes(expected);
+            return false;
+        }
+        case 'gt':
+            return typeof actual === 'number' && typeof expected === 'number' && actual > expected;
+        case 'gte':
+            return typeof actual === 'number' && typeof expected === 'number' && actual >= expected;
+        case 'lt':
+            return typeof actual === 'number' && typeof expected === 'number' && actual < expected;
+        case 'lte':
+            return typeof actual === 'number' && typeof expected === 'number' && actual <= expected;
+        default:
+            return false;
+    }
+};
+/**
+ * Evaluate a predicate (leaf or compound) against a result object. Compound
+ * forms short-circuit: all stops on first false, any stops on first true.
+ */
+const evalPredicate = (result, predicate) => {
+    if ('all' in predicate && Array.isArray(predicate.all)) {
+        for (const sub of predicate.all) {
+            if (!evalPredicate(result, sub))
+                return false;
+        }
+        return true;
+    }
+    if ('any' in predicate && Array.isArray(predicate.any)) {
+        for (const sub of predicate.any) {
+            if (evalPredicate(result, sub))
+                return true;
+        }
+        return false;
+    }
+    if ('not' in predicate && predicate.not && typeof predicate.not === 'object') {
+        return !evalPredicate(result, predicate.not);
+    }
+    const leaf = predicate;
+    if (typeof leaf.op !== 'string')
+        return false;
+    return evalLeaf(resolvePath(result, leaf.path), leaf.op, leaf.value);
+};
+/**
+ * Parse a `call`-style args argument that may arrive as a JSON string (older
+ * clients) or a plain object (new form). Returns { ok, args } or { ok: false,
+ * error } on malformed JSON.
+ */
+const parseCallArgs = (raw) => {
+    if (raw === undefined || raw === null)
+        return { args: {}, ok: true };
+    if (typeof raw === 'string') {
+        if (raw.length === 0)
+            return { args: {}, ok: true };
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return { args: parsed, ok: true };
+            }
+            return { error: 'Parsed args must be an object.', ok: false };
+        }
+        catch {
+            return { error: 'Invalid JSON in args.', ok: false };
+        }
+    }
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        return { args: raw, ok: true };
+    }
+    return { error: 'args must be an object or a JSON string.', ok: false };
+};
 /**
  * Recursively serializes a value to JSON with sorted object keys, producing a
  * stable canonical form that's safe to use as a dedup Map key. Arrays keep
@@ -128,12 +255,12 @@ class McpServerWrapper {
                 openWorldHint: true,
                 title: 'Call Tool',
             },
-            description: 'Call a tool registered by a React Native app client. Use list_tools first to see available tools. When multiple clients are connected, specify clientId; otherwise it is auto-picked.',
+            description: 'Call a tool registered by a React Native app client. Use list_tools first to see available tools. When multiple clients are connected, specify clientId; otherwise it is auto-picked. `args` accepts either a plain object or a JSON string — objects are preferred to avoid escaping quotes.',
             inputSchema: {
                 args: zod_1.z
-                    .string()
+                    .union([zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())])
                     .optional()
-                    .describe('Arguments as JSON string (e.g. {"screen": "AUTH_LOGIN_SCREEN"})'),
+                    .describe('Tool arguments as a plain object (e.g. { screen: "AUTH_LOGIN_SCREEN" }) or a JSON string.'),
                 clientId: zod_1.z
                     .string()
                     .optional()
@@ -143,102 +270,226 @@ class McpServerWrapper {
                     .describe(`Tool name in format "module${protocol_1.MODULE_SEPARATOR}method" (e.g. "navigation${protocol_1.MODULE_SEPARATOR}navigate")`),
             },
         }, async ({ args, clientId, tool }) => {
-            let parsedArgs = {};
-            if (args) {
-                try {
-                    parsedArgs = JSON.parse(args);
-                }
-                catch {
-                    return jsonError('Invalid JSON in args');
-                }
-            }
-            // Host dispatch — runs inline on the Node server, may work without any connected client
-            const hostEntry = this.hostToolMap.get(tool);
-            if (hostEntry) {
-                try {
-                    const result = await hostEntry.handler(parsedArgs, {
-                        bridge: this.bridge,
-                        requestedClientId: clientId,
-                    });
-                    return { content: this.formatResult(result) };
+            const parsed = parseCallArgs(args);
+            if (!parsed.ok)
+                return jsonError(parsed.error);
+            const dispatch = await this.dispatchTool(tool, parsed.args, clientId);
+            if (!dispatch.ok)
+                return jsonError(dispatch.error);
+            return { content: this.formatResult(dispatch.result) };
+        });
+        this.mcp.registerTool('wait_until', {
+            annotations: {
+                openWorldHint: true,
+                title: 'Wait Until',
+            },
+            description: `Poll a tool until its result satisfies a predicate, or timeout.
+
+Replaces "screenshot in a loop + sleep" with a declarative check. Typical use:
+  • wait for navigation to land on a screen
+  • wait for a spinner / toast to disappear
+  • wait for a fiber_tree.query to return matches (or stop returning them)
+  • wait for network.get_pending.length to hit 0
+
+PREDICATE
+  Leaf form: { op, path?, value? }
+    op: equals | notEquals | contains | notContains | exists | notExists | gt | gte | lt | lte
+    path drills through objects + array indices; arrays also expose .length.
+  Compound forms compose and nest:
+    { all: [predicate, ...] }   — AND
+    { any: [predicate, ...] }   — OR
+    { not: predicate }          — negation
+  Example: { all: [{op:"equals", path:"name", value:"CART"}, {op:"gt", path:"items.length", value:0}] }
+
+RETURNS
+  { ok: true, attempts, elapsedMs, matched? } on success — matched is the path-
+    resolved value for leaf predicates, omitted for compound.
+  { ok: false, reason, attempts, elapsedMs, lastResult, lastError? } on timeout.`,
+            inputSchema: {
+                args: zod_1.z
+                    .union([zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())])
+                    .optional()
+                    .describe('Arguments for the polled tool — object or JSON string.'),
+                clientId: zod_1.z.string().optional().describe('Target client ID, same semantics as `call`.'),
+                intervalMs: zod_1.z
+                    .number()
+                    .optional()
+                    .describe('Delay between poll attempts. Default 300, min 50, max 5000.'),
+                predicate: zod_1.z
+                    .object({})
+                    .passthrough()
+                    .describe('Leaf { op, path?, value? } or compound { all|any: [...] } / { not: predicate }. See tool description for ops and composition.'),
+                timeoutMs: zod_1.z
+                    .number()
+                    .optional()
+                    .describe('Total wait budget. Default 10000, min 500, max 60000.'),
+                tool: zod_1.z
+                    .string()
+                    .describe(`Tool name to poll (e.g. "navigation${protocol_1.MODULE_SEPARATOR}get_current_route").`),
+            },
+        }, async ({ args, clientId, intervalMs, predicate, timeoutMs, tool }) => {
+            const parsedArgs = parseCallArgs(args);
+            if (!parsedArgs.ok)
+                return jsonError(parsedArgs.error);
+            const pred = predicate;
+            const isLeaf = typeof pred.op === 'string';
+            const leafPath = isLeaf ? pred.path : undefined;
+            const timeout = Math.max(500, Math.min(60_000, timeoutMs ?? 10_000));
+            const interval = Math.max(50, Math.min(5_000, intervalMs ?? 300));
+            const started = Date.now();
+            let attempts = 0;
+            let lastResult;
+            let lastError;
+            while (Date.now() - started < timeout) {
+                attempts += 1;
+                const dispatch = await this.dispatchTool(tool, parsedArgs.args, clientId);
+                if (dispatch.ok) {
+                    lastResult = dispatch.result;
+                    if (evalPredicate(lastResult, pred)) {
+                        const payload = {
+                            attempts,
+                            elapsedMs: Date.now() - started,
+                            ok: true,
+                        };
+                        if (isLeaf) {
+                            payload.matched = resolvePath(lastResult, leafPath);
+                        }
+                        return {
+                            content: [{ text: JSON.stringify(payload, null, 2), type: 'text' }],
+                        };
+                    }
                 }
-                catch (err) {
-                    return jsonError(`Host tool "${tool}" threw: ${err.message}`);
+                else {
+                    lastError = dispatch.error;
                 }
-            }
-            const resolution = this.bridge.resolveClient(clientId);
-            if (!resolution.ok) {
-                return jsonError(resolution.error);
-            }
-            const client = resolution.client;
-            // Find the module by matching prefix in this client's modules
-            let mod;
-            let moduleName = '';
-            let methodName = '';
-            for (const m of client.modules) {
-                const prefix = `${m.name}${protocol_1.MODULE_SEPARATOR}`;
-                if (tool.startsWith(prefix)) {
-                    mod = m;
-                    moduleName = m.name;
-                    methodName = tool.slice(prefix.length);
+                const remaining = timeout - (Date.now() - started);
+                if (remaining <= 0)
                     break;
-                }
+                await new Promise((r) => {
+                    return setTimeout(r, Math.min(interval, remaining));
+                });
             }
-            // If no module matched, check for dynamic tool prefix or generic module__method
-            if (!mod) {
-                if (tool.startsWith(protocol_1.DYNAMIC_PREFIX)) {
-                    moduleName = `${protocol_1.MODULE_SEPARATOR}dynamic`;
-                    methodName = tool.slice(protocol_1.DYNAMIC_PREFIX.length);
-                }
-                else {
-                    const idx = tool.indexOf(protocol_1.MODULE_SEPARATOR);
-                    if (idx <= 0) {
-                        return jsonError(`Invalid tool name "${tool}". Use "module${protocol_1.MODULE_SEPARATOR}method" format.`);
-                    }
-                    moduleName = tool.slice(0, idx);
-                    methodName = tool.slice(idx + protocol_1.MODULE_SEPARATOR.length);
-                }
-                // Try dispatching via bridge — might be a dynamic tool registered on this client
-                try {
-                    const result = await this.bridge.call(client.id, moduleName, methodName, parsedArgs);
-                    return { content: this.formatResult(result) };
-                }
-                catch {
-                    const allModules = client.modules
-                        .map((m) => {
-                        return m.name;
-                    })
-                        .join(', ');
-                    const dynNames = [...client.dynamicTools.keys()].join(', ');
-                    return jsonError(`Tool "${tool}" not found on client '${client.id}'. Modules: ${allModules || '(none)'}. Dynamic: ${dynNames || '(none)'}`);
-                }
+            return {
+                content: [
+                    {
+                        text: JSON.stringify({
+                            attempts,
+                            elapsedMs: Date.now() - started,
+                            lastError,
+                            lastResult,
+                            ok: false,
+                            reason: lastError
+                                ? `Last dispatch failed: ${lastError}`
+                                : `Predicate did not hold within ${timeout}ms`,
+                        }, null, 2),
+                        type: 'text',
+                    },
+                ],
+            };
+        });
+        this.mcp.registerTool('assert', {
+            annotations: {
+                openWorldHint: true,
+                title: 'Assert',
+            },
+            description: `Single-shot assertion over a tool's result. Same predicate vocabulary (including { all / any / not }) as wait_until, but one attempt and a standardized diff on failure.
+
+Returns { pass: true, actual? } on success — actual is the path-resolved value for leaf predicates, omitted for compound.
+Returns { pass: false, actual, expected?, op?, path?, message?, result } on predicate failure.
+Returns { pass: false, error, message? } when the tool dispatch itself threw.
+
+Useful after wait_until as a checkpoint — the pair reads "do action → wait → assert" which produces a clean audit trail in session logs.`,
+            inputSchema: {
+                args: zod_1.z
+                    .union([zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())])
+                    .optional()
+                    .describe('Arguments for the asserted tool — object or JSON string.'),
+                clientId: zod_1.z.string().optional().describe('Target client ID, same semantics as `call`.'),
+                message: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Optional human-readable description of the check; echoed in the failure payload.'),
+                predicate: zod_1.z
+                    .object({})
+                    .passthrough()
+                    .describe('Leaf { op, path?, value? } or compound { all|any: [...] } / { not: predicate }. See wait_until for full semantics.'),
+                tool: zod_1.z
+                    .string()
+                    .describe(`Tool name to call once (e.g. "fiber_tree${protocol_1.MODULE_SEPARATOR}query").`),
+            },
+        }, async ({ args, clientId, message, predicate, tool }) => {
+            const parsedArgs = parseCallArgs(args);
+            if (!parsedArgs.ok)
+                return jsonError(parsedArgs.error);
+            const dispatch = await this.dispatchTool(tool, parsedArgs.args, clientId);
+            if (!dispatch.ok) {
+                return {
+                    content: [
+                        {
+                            text: JSON.stringify({ error: dispatch.error, message, pass: false }, null, 2),
+                            type: 'text',
+                        },
+                    ],
+                };
             }
-            const toolDef = mod.tools.find((t) => {
-                return t.name === methodName;
-            });
-            if (!toolDef) {
-                return jsonError(`Tool "${methodName}" not found in module "${moduleName}" on client '${client.id}'. Available: ${mod.tools
-                    .map((t) => {
-                    return t.name;
-                })
-                    .join(', ')}`);
+            const pred = predicate;
+            const isLeaf = typeof pred.op === 'string';
+            const leafPath = isLeaf ? pred.path : undefined;
+            const leafValue = isLeaf ? pred.value : undefined;
+            const leafOp = isLeaf ? pred.op : undefined;
+            const pass = evalPredicate(dispatch.result, pred);
+            const payload = { pass };
+            if (isLeaf)
+                payload.actual = resolvePath(dispatch.result, leafPath);
+            if (!pass) {
+                if (isLeaf) {
+                    payload.expected = leafValue;
+                    payload.op = leafOp;
+                    if (leafPath)
+                        payload.path = leafPath;
+                }
+                if (message)
+                    payload.message = message;
+                payload.result = dispatch.result;
             }
-            const result = await this.bridge.call(client.id, moduleName, methodName, parsedArgs, toolDef.timeout);
-            return { content: this.formatResult(result) };
+            return {
+                content: [{ text: JSON.stringify(payload, null, 2), type: 'text' }],
+            };
         });
         this.mcp.registerTool('list_tools', {
             annotations: {
                 readOnlyHint: true,
                 title: 'List Tools',
             },
-            description: 'Browse available tools with compact (schema-free) descriptions. Modules with identical shape across multiple clients are deduplicated into a single entry with a clientIds array. Use describe_tool to fetch the full input schema for a specific tool before calling it.',
-        }, async () => {
-            const clients = this.bridge.listClients();
+            description: 'Browse available tools with compact (schema-free) descriptions. Modules with identical shape across multiple clients are deduplicated into a single entry with a clientIds array. Use describe_tool to fetch the full input schema for a specific tool before calling it. Pass `module` to narrow to one module, `clientId` to narrow to one client, `compact: true` to drop long module-level descriptions.',
+            inputSchema: {
+                clientId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Narrow listing to a single client. Omit for all connected clients.'),
+                compact: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Drop module-level descriptions (still keeps per-tool one-liners). Default false.'),
+                module: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Narrow listing to a single module name (e.g. "fiber_tree", "host"). Omit for all.'),
+            },
+        }, async ({ clientId, compact, module }) => {
+            const allClients = this.bridge.listClients();
+            const clients = clientId
+                ? allClients.filter((c) => {
+                    return c.id === clientId;
+                })
+                : allClients;
             // Dedup tool groups across clients by canonical shape
             const dedupMap = new Map();
             for (const client of clients) {
                 const groups = this.buildToolGroups(client);
                 for (const group of groups) {
+                    if (module && group.module !== module)
+                        continue;
                     const key = canonicalizeGroup(group);
                     const existing = dedupMap.get(key);
                     if (existing) {
@@ -252,7 +503,7 @@ class McpServerWrapper {
             const modulesPayload = [...dedupMap.values()].map(({ clientIds, group }) => {
                 return {
                     clientIds,
-                    description: group.description,
+                    description: compact ? undefined : group.description,
                     name: group.module,
                     tools: group.tools.map((t) => {
                         return {
@@ -262,9 +513,13 @@ class McpServerWrapper {
                     }),
                 };
             });
-            const hostToolsPayload = this.hostModules.map((mod) => {
+            const hostToolsPayload = this.hostModules
+                .filter((mod) => {
+                return !module || mod.name === module;
+            })
+                .map((mod) => {
                 return {
-                    description: mod.description,
+                    description: compact ? undefined : mod.description,
                     name: mod.name,
                     tools: Object.entries(mod.tools).map(([toolName, tool]) => {
                         return {
@@ -536,6 +791,98 @@ class McpServerWrapper {
             return jsonError(`Tool '${tool}' exists on multiple clients with different schemas: ${candidates}. Specify clientId.`);
         });
     }
+    /**
+     * Execute a single tool by full name, returning the raw handler result.
+     * Used by both the `call` tool and meta-tools like `wait_until` that need to
+     * invoke other tools without going through the full MCP content wrapping.
+     */
+    async dispatchTool(tool, args, clientId) {
+        const hostEntry = this.hostToolMap.get(tool);
+        if (hostEntry) {
+            try {
+                const result = await hostEntry.handler(args, {
+                    bridge: this.bridge,
+                    dispatch: (nextTool, nextArgs, nextClientId) => {
+                        return this.dispatchTool(nextTool, nextArgs, nextClientId ?? clientId);
+                    },
+                    requestedClientId: clientId,
+                });
+                return { ok: true, result };
+            }
+            catch (err) {
+                return { error: `Host tool "${tool}" threw: ${err.message}`, ok: false };
+            }
+        }
+        const resolution = this.bridge.resolveClient(clientId);
+        if (!resolution.ok)
+            return { error: resolution.error, ok: false };
+        const client = resolution.client;
+        let mod;
+        let moduleName = '';
+        let methodName = '';
+        for (const m of client.modules) {
+            const prefix = `${m.name}${protocol_1.MODULE_SEPARATOR}`;
+            if (tool.startsWith(prefix)) {
+                mod = m;
+                moduleName = m.name;
+                methodName = tool.slice(prefix.length);
+                break;
+            }
+        }
+        if (!mod) {
+            if (tool.startsWith(protocol_1.DYNAMIC_PREFIX)) {
+                moduleName = `${protocol_1.MODULE_SEPARATOR}dynamic`;
+                methodName = tool.slice(protocol_1.DYNAMIC_PREFIX.length);
+            }
+            else {
+                const idx = tool.indexOf(protocol_1.MODULE_SEPARATOR);
+                if (idx <= 0) {
+                    return {
+                        error: `Invalid tool name "${tool}". Use "module${protocol_1.MODULE_SEPARATOR}method" format.`,
+                        ok: false,
+                    };
+                }
+                moduleName = tool.slice(0, idx);
+                methodName = tool.slice(idx + protocol_1.MODULE_SEPARATOR.length);
+            }
+            try {
+                const result = await this.bridge.call(client.id, moduleName, methodName, args);
+                return { ok: true, result };
+            }
+            catch {
+                const allModules = client.modules
+                    .map((m) => {
+                    return m.name;
+                })
+                    .join(', ');
+                const dynNames = [...client.dynamicTools.keys()].join(', ');
+                return {
+                    error: `Tool "${tool}" not found on client '${client.id}'. Modules: ${allModules || '(none)'}. Dynamic: ${dynNames || '(none)'}`,
+                    ok: false,
+                };
+            }
+        }
+        const toolDef = mod.tools.find((t) => {
+            return t.name === methodName;
+        });
+        if (!toolDef) {
+            return {
+                error: `Tool "${methodName}" not found in module "${moduleName}" on client '${client.id}'. Available: ${mod.tools
+                    .map((t) => {
+                    return t.name;
+                })
+                    .join(', ')}`,
+                ok: false,
+            };
+        }
+        try {
+            const result = await this.bridge.call(client.id, moduleName, methodName, args, toolDef.timeout);
+            return { ok: true, result };
+        }
+        catch (err) {
+            return { error: err.message, ok: false };
+        }
+    }
     buildToolGroups(client) {
         const groups = client.modules.map((mod) => {
             return {