Add env parameter to XcodeBuildMCP launch tools for passing environment variables

[kamal]

Summary

• Add env parameter to launch_app_sim, launch_app_logs_sim, and launch_app_device tools so environment variables can be passed to launched apps
• Add normalizeSimctlChildEnv utility (mirrors existing normalizeTestRunnerEnv) that auto-prefixes keys with SIMCTL_CHILD_
• For physical devices, passes env vars as --environment-variables KEY=VALUE flags to devicectl

Motivation

Launching apps against staging/dev environments requires passing environment variables to the app process. Previously this meant falling back to raw simctl commands (SIMCTL_CHILD_X=1 xcrun simctl launch ...). Now all three launch tools accept an env parameter directly.

[cameroncooke]

Thanks for this, will look at this shortly

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cameroncooke/XcodeBuildMCP/xcodebuildmcp@203

commit: 9c58546

[coderabbitai]

Walkthrough

The pull request adds optional environment variable support across app launching functionality. It introduces an env field to device launch parameters, simulator launch parameters, and log capture functions. A new utility function normalizeSimctlChildEnv prefixes environment variable keys with SIMCTL_CHILD_ for simulator launches. Test coverage is added for all related functionality. The changes affect launch_app_device, launch_app_sim, launch_app_logs_sim, and associated log capture utilities, with comprehensive test updates validating environment variable handling across device and simulator platforms.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding an env parameter to XcodeBuildMCP launch tools to pass environment variables.
Description check	✅ Passed	The description clearly relates to the changeset, detailing the env parameter additions to launch tools and the new normalizeSimctlChildEnv utility function.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/mcp/tools/device/launch_app_device.ts (1)

131-131: ⚠️ Potential issue | 🟡 Minor

Emoji in code string violates coding guidelines.

Line 131 contains a ✅ emoji in the response text. As per coding guidelines, **/*.{ts,tsx,js,jsx,json,md}: "No emojis in commits, issues, PR comments, or code".

🧹 Nitpick comments (2)

src/mcp/tools/device/__tests__/launch_app_device.test.ts (1)

139-139: any[] could be replaced with a typed array.

Consider using a more specific type (e.g. { command: string[] }[]) instead of any[] for the calls tracking array, consistent with the coding guideline against unnecessary any types. This also applies to existing instances on lines 55 and 102, though those predate this PR.

As per coding guidelines, **/*.{ts,tsx}: "No any types unless absolutely necessary in TypeScript code".

src/utils/environment.ts (1)

92-118: Consider extracting a shared helper to reduce duplication.

normalizeTestRunnerEnv and normalizeSimctlChildEnv are identical aside from the prefix string. A generic normalizePrefixedEnv(vars, prefix) helper would eliminate the duplication.

♻️ Suggested refactor

+function normalizePrefixedEnv(vars: Record<string, string>, prefix: string): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(vars ?? {})) {
+    if (value == null) continue;
+    const prefixedKey = key.startsWith(prefix) ? key : `${prefix}${key}`;
+    normalized[prefixedKey] = value;
+  }
+  return normalized;
+}
+
 export function normalizeTestRunnerEnv(vars: Record<string, string>): Record<string, string> {
-  const normalized: Record<string, string> = {};
-  for (const [key, value] of Object.entries(vars ?? {})) {
-    if (value == null) continue;
-    const prefixedKey = key.startsWith('TEST_RUNNER_') ? key : `TEST_RUNNER_${key}`;
-    normalized[prefixedKey] = value;
-  }
-  return normalized;
+  return normalizePrefixedEnv(vars, 'TEST_RUNNER_');
 }
 
 export function normalizeSimctlChildEnv(vars: Record<string, string>): Record<string, string> {
-  const normalized: Record<string, string> = {};
-  for (const [key, value] of Object.entries(vars ?? {})) {
-    if (value == null) continue;
-    const prefixedKey = key.startsWith('SIMCTL_CHILD_') ? key : `SIMCTL_CHILD_${key}`;
-    normalized[prefixedKey] = value;
-  }
-  return normalized;
+  return normalizePrefixedEnv(vars, 'SIMCTL_CHILD_');
 }