@godscene/shared 1.7.11

package/src/mcp/init-arg-utils.ts

@@ -0,0 +1,105 @@
+import type { z } from 'zod';
+import { getKeyAliases, isRecord } from '../key-alias-utils';
+import type { ToolSchema } from './types';
+
+function readAliasedValue(
+  args: Record<string, unknown>,
+  key: string,
+): unknown | undefined {
+  for (const alias of getKeyAliases(key)) {
+    if (alias in args) {
+      return args[alias];
+    }
+  }
+
+  return undefined;
+}
+
+function readNamespacedArg(
+  args: Record<string, unknown>,
+  namespace: string,
+  key: string,
+): unknown | undefined {
+  // Lookup order: namespace object first, then flat dotted form, then bare key
+  // fallback. Namespace-aware inputs win so multi-platform callers cannot be
+  // cross-contaminated by a top-level bare `deviceId` leaking into the wrong
+  // platform.
+  const namespacedArgs = readAliasedValue(args, namespace);
+  if (isRecord(namespacedArgs)) {
+    const nestedValue = readAliasedValue(namespacedArgs, key);
+    if (nestedValue !== undefined) {
+      return nestedValue;
+    }
+  }
+
+  const dottedValue = readAliasedValue(args, `${namespace}.${key}`);
+  if (dottedValue !== undefined) {
+    return dottedValue;
+  }
+
+  const directValue = readAliasedValue(args, key);
+  if (directValue !== undefined) {
+    return directValue;
+  }
+
+  return undefined;
+}
+
+export function extractNamespacedArgs<
+  TFieldName extends string,
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+>(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly TFieldName[],
+): TArgs | undefined {
+  const extracted: Record<string, unknown> = {};
+
+  for (const key of keys) {
+    const value = readNamespacedArg(args, namespace, key);
+    if (value !== undefined) {
+      extracted[key] = value;
+    }
+  }
+
+  return Object.keys(extracted).length > 0 ? (extracted as TArgs) : undefined;
+}
+
+export function sanitizeNamespacedArgs(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly string[],
+): Record<string, unknown> {
+  const excludedKeys = new Set<string>(getKeyAliases(namespace));
+
+  for (const key of keys) {
+    for (const alias of getKeyAliases(key)) {
+      excludedKeys.add(alias);
+    }
+
+    for (const alias of getKeyAliases(`${namespace}.${key}`)) {
+      excludedKeys.add(alias);
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(args).filter(([key]) => !excludedKeys.has(key)),
+  );
+}
+
+/**
+ * Build a flat MCP tool schema whose keys are dotted `"<namespace>.<field>"`.
+ *
+ * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
+ * that CLI (`--android.device-id`), MCP clients, and `--help` output all share
+ * the same spelling. `readNamespacedArg` understands all three input shapes:
+ * nested namespace object, dotted flat key, and bare key fallback.
+ */
+export function createNamespacedInitArgSchema(
+  namespace: string,
+  shape: Record<string, z.ZodTypeAny>,
+): ToolSchema {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, value]) => [`${namespace}.${key}`, value]),
+  );
+}

package/src/mcp/inject-report-html-plugin.ts

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAGIC_STRING = 'REPLACE_ME_WITH_REPORT_HTML';
+const REPLACED_MARK = '/*REPORT_HTML_REPLACED*/';
+const REG_EXP_FOR_REPLACE = /\/\*REPORT_HTML_REPLACED\*\/.*/;
+
+interface RslibPluginApi {
+  onAfterBuild: (callback: () => void) => void;
+}
+
+/**
+ * Rslib plugin to inject report HTML from @godscene/core dist into MCP bundle.
+ * This runs after build and reads the already-injected HTML from core.
+ *
+ * Prerequisites:
+ * - @godscene/report must be in devDependencies to ensure correct build order
+ * - @godscene/core dist must exist with injected HTML
+ *
+ * @param packageDir - The directory of the MCP package (use __dirname)
+ */
+export function injectReportHtmlFromCore(packageDir: string) {
+  return {
+    name: 'inject-report-html-from-core',
+    setup(api: RslibPluginApi) {
+      api.onAfterBuild(() => {
+        const coreUtilsPath = path.resolve(
+          packageDir,
+          '..',
+          'core',
+          'dist',
+          'lib',
+          'utils.js',
+        );
+
+        if (!fs.existsSync(coreUtilsPath)) {
+          console.warn(
+            '[inject-report-html] @godscene/core dist not found, skipping',
+          );
+          return;
+        }
+
+        const coreContent = fs.readFileSync(coreUtilsPath, 'utf-8');
+        if (!coreContent.includes(REPLACED_MARK)) {
+          console.warn(
+            '[inject-report-html] HTML not found in core dist. Ensure report builds first.',
+          );
+          return;
+        }
+
+        // Extract the JSON string after the marker
+        // JSON strings can contain escaped quotes, so we need to properly parse it
+        const markerIndex = coreContent.indexOf(REPLACED_MARK);
+        const jsonStart = markerIndex + REPLACED_MARK.length;
+
+        // Find the end of the JSON string by tracking quote escaping
+        let jsonEnd = jsonStart;
+        if (coreContent[jsonStart] === '"') {
+          jsonEnd = jsonStart + 1;
+          while (jsonEnd < coreContent.length) {
+            if (coreContent[jsonEnd] === '\\') {
+              jsonEnd += 2; // Skip escaped character
+            } else if (coreContent[jsonEnd] === '"') {
+              jsonEnd += 1; // Include closing quote
+              break;
+            } else {
+              jsonEnd += 1;
+            }
+          }
+        }
+
+        const jsonString = coreContent.slice(jsonStart, jsonEnd);
+        if (!jsonString || jsonString.length < 10) {
+          console.warn('[inject-report-html] Failed to extract HTML from core');
+          return;
+        }
+
+        const finalContent = `${REPLACED_MARK}${jsonString}`;
+        const distDir = path.join(packageDir, 'dist');
+
+        if (!fs.existsSync(distDir)) return;
+
+        const jsFiles = fs
+          .readdirSync(distDir)
+          .filter((f) => f.endsWith('.js'));
+        let injectedCount = 0;
+
+        for (const file of jsFiles) {
+          const filePath = path.join(distDir, file);
+          const content = fs.readFileSync(filePath, 'utf-8');
+
+          if (content.includes(REPLACED_MARK)) {
+            if (REG_EXP_FOR_REPLACE.test(content)) {
+              fs.writeFileSync(
+                filePath,
+                content.replace(REG_EXP_FOR_REPLACE, () => finalContent),
+              );
+              console.log(`[inject-report-html] Updated: ${file}`);
+              injectedCount++;
+            }
+          } else if (content.includes(`'${MAGIC_STRING}'`)) {
+            fs.writeFileSync(
+              filePath,
+              content.replace(`'${MAGIC_STRING}'`, () => finalContent),
+            );
+            console.log(`[inject-report-html] Injected: ${file}`);
+            injectedCount++;
+          }
+        }
+
+        if (injectedCount > 0) {
+          console.log(
+            `[inject-report-html] Completed: ${injectedCount} file(s)`,
+          );
+        }
+      });
+    },
+  };
+}

package/src/mcp/launcher-helper.ts

@@ -0,0 +1,200 @@
+import type { BaseMCPServer } from './base-server';
+import type { HttpLaunchOptions, LaunchMCPServerResult } from './base-server';
+import type { IMidsceneTools } from './types';
+
+export interface LaunchMCPServerOptions extends HttpLaunchOptions {
+  /**
+   * Whether to show server logs
+   * @default true
+   */
+  verbose?: boolean;
+}
+
+/**
+ * Generic agent type (avoid importing from @godscene/core to prevent circular deps)
+ */
+export interface GenericAgent<TDevice = any> {
+  interface: TDevice;
+  constructor: { name: string };
+}
+
+/**
+ * Additional information for logging server startup
+ */
+export interface StartupInfo {
+  port?: number;
+  host?: string;
+}
+
+export interface MCPServerLauncherConfig<
+  AgentType extends GenericAgent = GenericAgent,
+  ToolsManagerType extends IMidsceneTools = IMidsceneTools,
+> {
+  agent: AgentType;
+  platformName: string;
+  ToolsManagerClass: new (...args: any[]) => ToolsManagerType;
+  MCPServerClass: new (toolsManager?: ToolsManagerType) => BaseMCPServer;
+}
+
+/**
+ * Create a generic MCP server launcher for a given agent, tools manager, and MCP server.
+ *
+ * This helper centralizes the common wiring logic used by platform-specific launchers:
+ * it constructs a tools manager, attaches the provided `agent` to it, then instantiates
+ * the `MCPServerClass` and exposes convenience methods to start the server over stdio
+ * (`launch`) or HTTP (`launchHttp`).
+ *
+ * Use this helper when adding a new platform-specific launcher or when you want to
+ * avoid duplicating boilerplate code for starting an MCP server. Typically, callers
+ * provide:
+ * - an `agent` instance that contains the underlying device on its `interface` property
+ * - a `ToolsManagerClass` that knows how to expose tools for that agent
+ * - an `MCPServerClass` that implements the MCP protocol and supports `launch` and
+ *   `launchHttp` methods.
+ *
+ * The returned object has two methods:
+ * - `launch(options?)` to start the server using stdio transport
+ * - `launchHttp(options)` to start the server using HTTP transport
+ * Both methods accept a `verbose` flag to control console logging.
+ *
+ * @param config Configuration describing the agent, platform name (for logging),
+ *               tools manager implementation, and MCP server implementation.
+ *
+ * @returns An object with `launch` and `launchHttp` methods to start the MCP server.
+ *
+ * @example
+ * ```typescript
+ * import { createMCPServerLauncher } from '@godscene/shared/mcp';
+ * import { Agent } from '@godscene/core/agent';
+ * import { WebMidsceneTools } from './web-tools';
+ * import { WebMCPServer } from './server';
+ *
+ * const agent = new Agent();
+ * const launcher = createMCPServerLauncher({
+ *   agent,
+ *   platformName: 'Web',
+ *   ToolsManagerClass: WebMidsceneTools,
+ *   MCPServerClass: WebMCPServer,
+ * });
+ *
+ * // Start with stdio
+ * await launcher.launch({ verbose: true });
+ *
+ * // Or start with HTTP
+ * await launcher.launchHttp({ port: 3000, host: 'localhost' });
+ * ```
+ *
+ * @internal
+ */
+export function createMCPServerLauncher<
+  AgentType extends GenericAgent,
+  ToolsManagerType extends IMidsceneTools,
+>(config: MCPServerLauncherConfig<AgentType, ToolsManagerType>) {
+  const { agent, platformName, ToolsManagerClass, MCPServerClass } = config;
+
+  /**
+   * Validate that the agent has the required interface property
+   * @throws {Error} If agent.interface is missing
+   */
+  function validateAgent(): void {
+    const device = agent.interface;
+    if (!device) {
+      throw new Error(
+        `Agent must have an 'interface' property that references the underlying device.
+Please ensure your agent instance is properly initialized with a device interface.
+Expected: agent.interface to be defined, but got: ${typeof device}
+Solution: Check that your agent constructor properly sets the interface property.`,
+      );
+    }
+  }
+
+  /**
+   * Create and configure a tools manager with the agent
+   * @returns Configured tools manager instance
+   */
+  function createToolsManager(): ToolsManagerType {
+    const toolsManager = new ToolsManagerClass();
+    // Type-safe agent injection: define explicit interface for tools manager with agent
+    interface ToolsManagerWithAgent extends IMidsceneTools {
+      agent: AgentType;
+    }
+    (toolsManager as unknown as ToolsManagerWithAgent).agent = agent;
+    return toolsManager;
+  }
+
+  /**
+   * Log server startup information
+   * @param mode - Transport mode ('stdio' or 'HTTP')
+   * @param additionalInfo - Additional info to log (e.g., port, host)
+   */
+  function logStartupInfo(
+    mode: 'stdio' | 'HTTP',
+    additionalInfo?: StartupInfo,
+  ): void {
+    const device = agent.interface;
+    console.log(`Starting Midscene ${platformName} MCP Server (${mode})...`);
+    console.log(`Agent: ${agent.constructor.name}`);
+    console.log(`Device: ${device.constructor.name}`);
+
+    if (additionalInfo?.port !== undefined) {
+      console.log(`Port: ${additionalInfo.port}`);
+    }
+    if (additionalInfo?.host) {
+      console.log(`Host: ${additionalInfo.host}`);
+    }
+  }
+
+  return {
+    /**
+     * Launch the MCP server with stdio transport
+     */
+    async launch(
+      options: { verbose?: boolean } = {},
+    ): Promise<LaunchMCPServerResult> {
+      const { verbose = true } = options;
+
+      validateAgent();
+
+      if (verbose) {
+        logStartupInfo('stdio');
+      }
+
+      const toolsManager = createToolsManager();
+      const server = new MCPServerClass(toolsManager);
+      const result = await server.launch();
+
+      if (verbose) {
+        console.log(`${platformName} MCP Server started (stdio mode)`);
+      }
+
+      return result;
+    },
+
+    /**
+     * Launch the MCP server with HTTP transport
+     */
+    async launchHttp(
+      options: LaunchMCPServerOptions,
+    ): Promise<LaunchMCPServerResult> {
+      const { port, host = 'localhost', verbose = true } = options;
+
+      validateAgent();
+
+      if (verbose) {
+        logStartupInfo('HTTP', { port, host });
+      }
+
+      const toolsManager = createToolsManager();
+      const server = new MCPServerClass(toolsManager);
+      const result = await server.launchHttp({ port, host });
+
+      if (verbose) {
+        console.log(
+          `${platformName} MCP Server started on http://${result.host}:${result.port}/mcp`,
+        );
+      }
+
+      return result;
+    },
+  };
+}