feat: env var session defaults and setup --format mcp-json

[ichoosetoaccept]

Summary

Closes #267.

Config file discovery via process.cwd() is unreliable across MCP clients (Windsurf sets cwd=/, Codex has the same issue, Claude Desktop has no cwd field). Environment variables are the de facto standard for MCP server configuration — every client implements the env field. This PR closes the gap for session defaults and makes env vars the documented primary path for MCP client integration.

Changes

src/utils/config-store.ts

• Add readEnvSessionDefaults() — parses all 15 session default env vars:
  XCODEBUILDMCP_WORKSPACE_PATH, XCODEBUILDMCP_PROJECT_PATH, XCODEBUILDMCP_SCHEME, XCODEBUILDMCP_CONFIGURATION, XCODEBUILDMCP_SIMULATOR_NAME, XCODEBUILDMCP_SIMULATOR_ID, XCODEBUILDMCP_DEVICE_ID, XCODEBUILDMCP_DERIVED_DATA_PATH, XCODEBUILDMCP_PLATFORM, XCODEBUILDMCP_BUNDLE_ID, XCODEBUILDMCP_USE_LATEST_OS, XCODEBUILDMCP_SUPPRESS_WARNINGS, XCODEBUILDMCP_PREFER_XCODEBUILD, XCODEBUILDMCP_ARCH, XCODEBUILDMCP_SIMULATOR_PLATFORM
• Wire env layer into resolveSessionDefaults() with explicit precedence: session_set_defaults tool > config file > env vars

src/cli/commands/setup.ts

• Add --format option (yaml | mcp-json) to xcodebuildmcp setup
• When --format mcp-json: runs the same interactive wizard but prints a ready-to-paste MCP client config JSON block instead of writing config.yaml

docs/CONFIGURATION.md

• Restructured: env vars documented first as the recommended MCP client integration path
• Remove the "Environment variables (legacy)" section and label
• Add session default env var reference table
• Add example MCP config JSON block
• Add xcodebuildmcp setup --format mcp-json reference
• Add "Configuration layering" section documenting tool > file > env precedence

CHANGELOG.md

• Add [Unreleased] entries for the new env var support and --format mcp-json

Testing

• New test: reads session defaults from env vars — verifies all string/bool env vars are parsed correctly
• New test: file config session defaults take precedence over env var session defaults — verifies file wins over env
• New test: outputs MCP config JSON when format is mcp-json — verifies JSON structure, command, args, and env fields
• All 1462 existing tests pass

Example

This replaces a config.yaml entirely:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
      "env": {
        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,macos,debugging,logging",
        "XCODEBUILDMCP_WORKSPACE_PATH": "/path/to/MyApp.xcworkspace",
        "XCODEBUILDMCP_SCHEME": "MyApp",
        "XCODEBUILDMCP_PLATFORM": "macOS"
      }
    }
  }
}

Or generate it interactively:

xcodebuildmcp setup --format mcp-json

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Env not stored, lost on session defaults refresh

Medium Severity

initConfigStore accepts an env parameter and passes it through to resolveSessionDefaults, but env is never stored in ConfigStoreState. When refreshResolvedSessionFields() is later called (via persistSessionDefaultsPatch or persistActiveSessionDefaultsProfile), it calls resolveSessionDefaults without env, falling back to process.env. If the original env differed from process.env, the env-based session defaults silently change after any session defaults patch.

Additional Locations (1)

• src/utils/config-store.ts#L575-L578