mobile-debug-mcp 0.24.6 → 0.24.7

package/dist/utils/android/utils.js

@@ -57,23 +57,36 @@ export function ensureAdbAvailable() {
         return { adbCmd: adb, ok: false, error: String(err) };
     }
 }
+function mergeEnv(overrides) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(overrides || {})) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    return env;
+}
 /**
  * Prepare Gradle execution options for building an Android project.
  * Returns execCmd (wrapper or gradle), base gradleArgs array, and spawn options including env.
  */
-export async function prepareGradle(projectPath) {
+export async function prepareGradle(projectPath, envOverrides = {}) {
+    const env = mergeEnv(envOverrides);
     const gradlewPath = path.join(projectPath, 'gradlew');
     const gradleCmd = existsSync(gradlewPath) ? './gradlew' : 'gradle';
     const execCmd = existsSync(gradlewPath) ? gradlewPath : gradleCmd;
     // Start with a default task; callers may append/override via env flags
-    const gradleArgs = [process.env.MCP_GRADLE_TASK || 'assembleDebug'];
+    const gradleArgs = [env.MCP_GRADLE_TASK || 'assembleDebug'];
     // Respect generic MCP_BUILD_JOBS and Android-specific MCP_GRADLE_WORKERS
-    const workers = process.env.MCP_GRADLE_WORKERS || process.env.MCP_BUILD_JOBS;
+    const workers = env.MCP_GRADLE_WORKERS || env.MCP_BUILD_JOBS;
     if (workers) {
         gradleArgs.push(`--max-workers=${workers}`);
     }
     // Respect gradle cache env: default enabled; set MCP_GRADLE_CACHE=0 to disable
-    if (process.env.MCP_GRADLE_CACHE === '0') {
+    if (env.MCP_GRADLE_CACHE === '0') {
         gradleArgs.push('-Dorg.gradle.caching=false');
     }
     const detectedJavaHome = await detectJavaHome().catch(() => undefined);
@@ -85,7 +98,6 @@ export async function prepareGradle(projectPath) {
     catch {
         gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] };
     }
-    const env = Object.assign({}, process.env);
     // Ensure child processes can find Android platform-tools (adb, etc.) by
     // prepending the platform-tools directory to PATH for spawned processes.
     const adbPath = resolveAdbCmd();

package/dist/utils/cli/idb/check-idb.js

@@ -24,7 +24,7 @@ async function runInstaller() {
         // prefer invoking the TS script via npx/tsx to ensure environment
         const runner = which('npx') ? 'npx' : which('tsx') ? 'tsx' : null;
         if (runner) {
-            const args = runner === 'npx' ? ['tsx', './src/cli/idb/install-idb.ts'] : ['./src/cli/idb/install-idb.ts'];
+            const args = runner === 'npx' ? ['tsx', './src/utils/cli/idb/install-idb.ts'] : ['./src/utils/cli/idb/install-idb.ts'];
             const res = spawnSync(runner, args, { stdio: 'inherit' });
             return typeof res.status === 'number' ? res.status === 0 : false;
         }

package/docs/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## [0.24.6]
-- minor changes
+## [0.24.7]
+- Aligned runtime metadata with the published package version.
+- Fixed stale CLI helper paths in npm scripts and the `idb` healthcheck helper.
+- Simplified ESLint configuration by keeping the flat config and removing legacy config files.
+- Updated CI to use the current automated device test runner.
+- Tightened server handler argument parsing and added contract coverage for version and required-argument error responses.
+- Scoped temporary build environment overrides to the duration of each build helper call and added regression coverage for env restoration.
 
 ## [0.24.5]
 - Improved snapshots
@@ -27,7 +32,7 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 
 ## [0.23.0]
 - Added network monitoring
-- Added 
+- Added action-outcome classification tooling for backend-driven flows without visible UI changes.
 
 ## [0.22.0]
 - Added a portable `test-authoring` skill package and documented the repository's vendor-neutral skill format
@@ -38,14 +43,14 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 - Fixed incorrect timeout
 
 ## [0.21.4]
-- updated `wait_for_ui` with better contract and observability
-- update `get_logs` to get better output
+- Updated `wait_for_ui` with better contract and observability
+- Updated `get_logs` to return more useful structured output
 
 ## [0.21.3]
 - Added structured logs
 
 ## [0.21.2]
-- Fixed screenshots not working, imnproved tool
+- Fixed screenshots not working and improved the tool output
 
 ## [0.21.1]
 - Removed wait_for_element and renamed observe_until to wait_for_ui (obsolete references removed)
@@ -54,7 +59,7 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 - Added `wait_for_ui` as a tool for agents to wait for things like API requests
 
 ## [0.20.1]
-- Fixes gradle home issue for android
+- Fixed Gradle home handling for Android
 
 ## [0.20.0]
 - Added `get_system_status` tool and refactored system health checks into `src/system`.
@@ -63,8 +68,8 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 
 
 ## [0.19.2]
-- Added healthcheck improvments
-- Added skills 
+- Added healthcheck improvements
+- Added reusable agent skills
 
 ## [0.19.1]
 
@@ -113,7 +118,7 @@ All notable changes to the **Mobile Debug MCP** project will be documented in th
 ## [0.12.1]
 - Improve iOS build/install reliability: project auto-scan, explicit simulator destination, configurable watchdog timeout (MCP_XCODEBUILD_TIMEOUT) and retries (MCP_XCODEBUILD_RETRIES), and DerivedData fallback for locating .app artifacts.
 - Make install_app capable of building iOS projects before installing so agents can autonomously fix, build, install and validate apps.
-- Migrate CLI scripts into typed src/cli/* modules and update npm scripts; fix ESM import paths and lint issues.
+- Migrate CLI scripts into typed source modules and update npm scripts; fix ESM import paths and lint issues.
 - Add preflight checks and idb resolution helpers (getIdbCmd, isIDBInstalled) and add idb_companion health checks.
 - Capture build stdout/stderr into build-results/ for easier diagnostics and surfaced suggestions when KMP frameworks are missing.
 - Add device test runner under test/device and gate device-dependent tests behind RUN_DEVICE_TESTS.

package/eslint.config.js

@@ -3,7 +3,6 @@ import tsPlugin from '@typescript-eslint/eslint-plugin'
 import unusedImports from 'eslint-plugin-unused-imports'
 
 export default [
-  // Files/directories to ignore
   {
     ignores: [
       'dist/',
@@ -11,55 +10,11 @@ export default [
       '.git/',
       '.vscode/',
       'coverage/',
-      '.env',
+      '.env'
     ]
   },
-  // Apply rules to JS/TS source
   {
-    files: ['src/**/*.ts', 'src/**/*.js'],
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: {
-        ecmaVersion: 2020,
-        sourceType: 'module',
-        project: './tsconfig.json'
-      }
-    },
-    plugins: {
-      '@typescript-eslint': tsPlugin,
-      'unused-imports': unusedImports
-    },
-    rules: {
-      // Use plugin to error on unused imports and provide autofix where possible
-      'unused-imports/no-unused-imports': 'error',
-      'unused-imports/no-unused-vars': ['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
-      // Disable the default TS rule to avoid duplicate warnings
-      '@typescript-eslint/no-unused-vars': 'off'
-    }
-  },
-  // Apply lighter rules to test files (no project reference to avoid TS project parsing)
-  {
-    files: ['test/**/*.ts', 'test/**/*.js'],
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: {
-        ecmaVersion: 2020,
-        sourceType: 'module'
-      }
-    },
-    plugins: {
-      '@typescript-eslint': tsPlugin,
-      'unused-imports': unusedImports
-    },
-    rules: {
-      'unused-imports/no-unused-imports': 'error',
-      'unused-imports/no-unused-vars': ['error', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
-      '@typescript-eslint/no-unused-vars': 'off'
-    }
-  },
-  // Apply rules to CLI tooling
-  {
-    files: ['src/cli/**/*.ts', 'src/cli/**/*.js'],
+    files: ['src/**/*.ts', 'src/**/*.js', 'test/**/*.ts', 'test/**/*.js'],
     languageOptions: {
       parser: tsParser,
       parserOptions: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.24.6",
+  "version": "0.24.7",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -10,15 +10,16 @@
     "build": "tsc",
     "start": "node ./dist/server.js",
     "prepare": "npm run build",
-    "healthcheck": "tsx ./src/cli/idb/check-idb.ts",
-    "install-idb": "tsx ./src/cli/idb/install-idb.ts",
-    "preflight-ios": "tsx ./src/cli/ios/preflight-ios.ts",
+    "healthcheck": "tsx ./src/utils/cli/idb/check-idb.ts",
+    "install-idb": "tsx ./src/utils/cli/idb/install-idb.ts",
+    "preflight-ios": "tsx ./src/utils/cli/ios/preflight-ios.ts",
     "test:unit": "tsx test/unit/index.ts",
     "test:integration": "npm run test:device",
     "test:device": "npm run build && tsx test/device/index.ts",
     "test": "npm run test:unit",
-    "lint": "eslint --ext .ts,.js src test --quiet",
-    "lint:fix": "eslint --ext .ts,.js src test --fix"
+    "lint": "eslint src test --quiet",
+    "lint:fix": "eslint src test --fix",
+    "verify": "npm run lint && npm run build && npm run test:unit"
   },
 
   "engines": {

package/src/manage/android.ts

@@ -2,22 +2,33 @@ import { promises as fs } from 'fs'
 import { spawn } from 'child_process'
 import path from 'path'
 import { existsSync } from 'fs'
-import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js'
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk, prepareGradle } from '../utils/android/utils.js'
 import { execAdbWithDiagnostics } from '../utils/diagnostics.js'
 import { detectJavaHome } from '../utils/java.js'
 import { AndroidObserve } from '../observe/android.js'
 import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
+type BuildEnv = Record<string, string | undefined>
+
+export interface AndroidBuildOptions {
+  variant?: string
+  env?: BuildEnv
+}
+
 export class AndroidManage {
   private isTestOnlyInstallFailure(output: string | undefined): boolean {
     return typeof output === 'string' && output.includes('INSTALL_FAILED_TEST_ONLY')
   }
 
-  async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string }> {
-    void _variant
+  async build(projectPath: string, optionsOrVariant?: string | AndroidBuildOptions): Promise<{ artifactPath: string, output?: string } | { error: string }> {
+    const options: AndroidBuildOptions = typeof optionsOrVariant === 'string' ? { variant: optionsOrVariant } : (optionsOrVariant || {})
     try {
+      const env = {
+        ...(options.env || {}),
+        ...(options.variant ? { MCP_GRADLE_TASK: options.variant } : {})
+      }
       // Always use the shared prepareGradle utility for consistent env/setup
-      const { execCmd, gradleArgs, spawnOpts } = await (await import('../utils/android/utils.js')).prepareGradle(projectPath)
+      const { execCmd, gradleArgs, spawnOpts } = await prepareGradle(projectPath, env)
       await new Promise<void>((resolve, reject) => {
         const proc = spawn(execCmd, gradleArgs, spawnOpts)
         let stderr = ''
@@ -43,13 +54,13 @@ export class AndroidManage {
 
     let apkToInstall: string = apkPath
     try {
-      const stat = await fs.stat(apkPath).catch(() => null)
-      if (stat && stat.isDirectory()) {
-        const detectedJavaHome = await detectJavaHome().catch(() => undefined)
-        const env = Object.assign({}, process.env)
-        if (detectedJavaHome) {
-          if (env.JAVA_HOME !== detectedJavaHome) {
-            env.JAVA_HOME = detectedJavaHome
+        const stat = await fs.stat(apkPath).catch(() => null)
+        if (stat && stat.isDirectory()) {
+          const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+          const env = { ...process.env }
+          if (detectedJavaHome) {
+            if (env.JAVA_HOME !== detectedJavaHome) {
+              env.JAVA_HOME = detectedJavaHome
             env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
             console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome)
           }

package/src/manage/index.ts

@@ -60,25 +60,37 @@ export async function detectProjectPlatform(projectPath: string): Promise<'ios'|
   }
 }
 
+type BuildEnv = Record<string, string | undefined>
+
+function mergeDefinedEnv(...parts: Array<BuildEnv | undefined>): BuildEnv {
+  const merged: BuildEnv = {}
+  for (const part of parts) {
+    if (!part) continue
+    for (const [key, value] of Object.entries(part)) {
+      if (typeof value === 'undefined') continue
+      merged[key] = value
+    }
+  }
+  return merged
+}
+
 export class ToolsManage {
   static async build_android({ projectPath, gradleTask, maxWorkers, gradleCache, forceClean }: { projectPath: string, gradleTask?: string, maxWorkers?: number, gradleCache?: boolean, forceClean?: boolean }) {
     const android = new AndroidManage()
-    // prepare gradle options via environment hints
-    if (typeof maxWorkers === 'number') process.env.MCP_GRADLE_WORKERS = String(maxWorkers)
-    if (typeof gradleCache === 'boolean') process.env.MCP_GRADLE_CACHE = gradleCache ? '1' : '0'
-    if (forceClean) process.env.MCP_FORCE_CLEAN_ANDROID = '1'
     const task = gradleTask || 'assembleDebug'
-    const artifact = await (android as any).build(projectPath, task)
-    return artifact
+    return await (android as any).build(projectPath, {
+      variant: task,
+      env: mergeDefinedEnv({
+        MCP_GRADLE_TASK: task,
+        MCP_GRADLE_WORKERS: typeof maxWorkers === 'number' ? String(maxWorkers) : undefined,
+        MCP_GRADLE_CACHE: typeof gradleCache === 'boolean' ? (gradleCache ? '1' : '0') : undefined,
+        MCP_FORCE_CLEAN_ANDROID: forceClean ? '1' : undefined
+      })
+    })
   }
 
   static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }: { projectPath: string, workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, buildJobs?: number, forceClean?: boolean }) {
     const ios = new iOSManage()
-    // Use provided options rather than env-only; still set env fallbacks for downstream tools
-    if (derivedDataPath) process.env.MCP_DERIVED_DATA = derivedDataPath
-    if (typeof buildJobs === 'number') process.env.MCP_BUILD_JOBS = String(buildJobs)
-    if (forceClean) process.env.MCP_FORCE_CLEAN_IOS = '1'
-    if (destinationUDID) process.env.MCP_XCODE_DESTINATION_UDID = destinationUDID
 
     const opts: any = {}
     if (_workspace) opts.workspace = _workspace
@@ -86,12 +98,21 @@ export class ToolsManage {
     if (_scheme) opts.scheme = _scheme
     if (destinationUDID) opts.destinationUDID = destinationUDID
     if (derivedDataPath) opts.derivedDataPath = derivedDataPath
-    if (forceClean) opts.forceClean = forceClean
+    if (typeof buildJobs === 'number') opts.buildJobs = buildJobs
+    if (typeof forceClean === 'boolean') opts.forceClean = forceClean
     // prefer explicit xcodebuild path from env
     if (process.env.XCODEBUILD_PATH) opts.xcodeCmd = process.env.XCODEBUILD_PATH
 
-    const artifact = await (ios as any).build(projectPath, opts)
-    return artifact
+    return await (ios as any).build(projectPath, {
+      ...opts,
+      env: mergeDefinedEnv({
+        MCP_DERIVED_DATA: derivedDataPath,
+        MCP_XCODE_JOBS: typeof buildJobs === 'number' ? String(buildJobs) : undefined,
+        MCP_FORCE_CLEAN: typeof forceClean === 'boolean' ? (forceClean ? '1' : '0') : undefined,
+        MCP_XCODE_DESTINATION_UDID: destinationUDID,
+        XCODEBUILD_PATH: process.env.XCODEBUILD_PATH
+      })
+    })
   }
 
   static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }: { projectPath: string, platform?: 'android'|'ios', buildMode?: 'debug'|'release'|'profile', maxWorkers?: number, forceClean?: boolean }) {
@@ -178,11 +199,11 @@ export class ToolsManage {
     const chosen = platform || 'android'
     if (chosen === 'android') {
       const android = new AndroidManage()
-      const artifact = await (android as any).build(projectPath, variant)
+      const artifact = await (android as any).build(projectPath, { variant })
       return artifact
     } else {
       const ios = new iOSManage()
-      const artifact = await (ios as any).build(projectPath, variant)
+      const artifact = await (ios as any).build(projectPath, { variant })
       return artifact
     }
   }

package/src/manage/ios.ts

@@ -5,12 +5,25 @@ import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validate
 import { iOSObserve } from "../observe/ios.js"
 import path from "path"
 
+type BuildEnv = Record<string, string | undefined>
+
+export interface IOSBuildOptions {
+  workspace?: string
+  project?: string
+  scheme?: string
+  destinationUDID?: string
+  derivedDataPath?: string
+  buildJobs?: number
+  forceClean?: boolean
+  xcodeCmd?: string
+  env?: BuildEnv
+}
+
 export class iOSManage {
-  async build(projectPath: string, optsOrVariant?: string | { workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, forceClean?: boolean, xcodeCmd?: string }): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
+  async build(projectPath: string, optsOrVariant?: string | IOSBuildOptions): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
     // Support legacy variant string as second arg
-    let opts: any = {}
-    if (typeof optsOrVariant === 'string') opts.variant = optsOrVariant
-    else opts = optsOrVariant || {}
+    const opts: IOSBuildOptions = typeof optsOrVariant === 'string' ? {} : (optsOrVariant || {})
+    const env = { ...process.env, ...(opts.env || {}) }
 
     try {
       // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
@@ -65,7 +78,7 @@ export class iOSManage {
       }
 
       // Determine destination: prefer explicit option, then env var, otherwise use booted simulator UDID
-      let destinationUDID = opts.destinationUDID || process.env.MCP_XCODE_DESTINATION_UDID || process.env.MCP_XCODE_DESTINATION || ''
+      let destinationUDID = opts.destinationUDID || env.MCP_XCODE_DESTINATION_UDID || env.MCP_XCODE_DESTINATION || ''
       if (!destinationUDID) {
         try {
           const meta = await getIOSDeviceMetadata('booted')
@@ -74,7 +87,7 @@ export class iOSManage {
       }
 
       // Determine xcode command early so it can be used when detecting schemes
-      const xcodeCmd = opts.xcodeCmd || process.env.XCODEBUILD_PATH || 'xcodebuild'
+      const xcodeCmd = opts.xcodeCmd || env.XCODEBUILD_PATH || 'xcodebuild'
 
       // Determine available schemes by querying xcodebuild -list rather than guessing
       async function detectScheme(xcodeCmdInner: string, workspacePath?: string, projectPathFull?: string, cwd?: string): Promise<string | null> {
@@ -98,11 +111,11 @@ export class iOSManage {
       let chosenScheme: string | null = opts.scheme || null
 
       // Derived data and result bundle (agent-configurable)
-      const derivedDataPath = opts.derivedDataPath || process.env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData')
+      const derivedDataPath = opts.derivedDataPath || env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData')
       // Use unique result bundle path by default to avoid collisions
-      const resultBundlePath = process.env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`)
-      const xcodeJobs = parseInt(process.env.MCP_XCODE_JOBS || '', 10) || 4
-      const forceClean = opts.forceClean || process.env.MCP_FORCE_CLEAN === '1'
+      const resultBundlePath = env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`)
+      const xcodeJobs = typeof opts.buildJobs === 'number' ? opts.buildJobs : (parseInt(env.MCP_XCODE_JOBS || '', 10) || 4)
+      const forceClean = typeof opts.forceClean === 'boolean' ? opts.forceClean : env.MCP_FORCE_CLEAN === '1'
 
       // ensure result dirs exist
       await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => {})
@@ -147,8 +160,8 @@ export class iOSManage {
       await fs.mkdir(resultsDir, { recursive: true }).catch(() => {})
 
 
-      const XCODEBUILD_TIMEOUT = parseInt(process.env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000 // default 3 minutes
-      const MAX_RETRIES = parseInt(process.env.MCP_XCODEBUILD_RETRIES || '', 10) || 1
+      const XCODEBUILD_TIMEOUT = parseInt(env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000 // default 3 minutes
+      const MAX_RETRIES = parseInt(env.MCP_XCODEBUILD_RETRIES || '', 10) || 1
 
       const tries = MAX_RETRIES + 1
       let lastStdout = ''
@@ -157,8 +170,8 @@ export class iOSManage {
 
       for (let attempt = 1; attempt <= tries; attempt++) {
         // Run xcodebuild with a watchdog
-        const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((resolve) => {
-          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir })
+          const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((resolve) => {
+          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir, env })
           let stdout = ''
           let stderr = ''
 
@@ -215,7 +228,7 @@ export class iOSManage {
       if (lastErr) {
         // Include diagnostics and result bundle path when available; provide structured info useful for agents
         const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`
-        const envSnapshot = { PATH: process.env.PATH }
+          const envSnapshot = { PATH: env.PATH }
         return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: (lastErr as any).code || null, invokedCommand, cwd: projectRootDir, envSnapshot } }
       }
 

package/src/server/common.ts

@@ -20,6 +20,56 @@ export type ToolCallResult = Awaited<ReturnType<typeof wrapResponse>> | {
 }
 export type ToolHandler = (args: ToolCallArgs) => Promise<ToolCallResult>
 
+export function getStringArg(args: ToolCallArgs, key: string): string | undefined {
+  const value = args[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+export function requireStringArg(args: ToolCallArgs, key: string): string {
+  const value = getStringArg(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid string argument: ${key}`)
+  return value
+}
+
+export function getNumberArg(args: ToolCallArgs, key: string): number | undefined {
+  const value = args[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+export function requireNumberArg(args: ToolCallArgs, key: string): number {
+  const value = getNumberArg(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid number argument: ${key}`)
+  return value
+}
+
+export function getBooleanArg(args: ToolCallArgs, key: string): boolean | undefined {
+  const value = args[key]
+  return typeof value === 'boolean' ? value : undefined
+}
+
+export function requireBooleanArg(args: ToolCallArgs, key: string): boolean {
+  const value = getBooleanArg(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid boolean argument: ${key}`)
+  return value
+}
+
+export function getObjectArg<T extends Record<string, unknown>>(args: ToolCallArgs, key: string): T | undefined {
+  const value = args[key]
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  return value as T
+}
+
+export function requireObjectArg<T extends Record<string, unknown>>(args: ToolCallArgs, key: string): T {
+  const value = getObjectArg<T>(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid object argument: ${key}`)
+  return value
+}
+
+export function getArrayArg<T>(args: ToolCallArgs, key: string): T[] | undefined {
+  const value = args[key]
+  return Array.isArray(value) ? value as T[] : undefined
+}
+
 let actionSequence = 0
 
 export function nextActionId(actionType: string, timestamp: number) {