ref: Migrate next-steps to manifest-driven templates

NEXT_STEPS_MIGRATION_TODO.md

@@ -0,0 +1,27 @@
+# Next Steps Migration TODO
+
+Generated: 2026-02-11 19:12:27 UTC
+
+## Remaining tool files with inline nextSteps
+- [x] src/mcp/tools/debugging/debug_attach_sim.ts:148
+- [x] src/mcp/tools/device/get_device_app_path.ts:140
+- [x] src/mcp/tools/device/launch_app_device.ts:135
+- [x] src/mcp/tools/device/list_devices.ts:391
+- [x] src/mcp/tools/logging/start_device_log_cap.ts:665
+- [x] src/mcp/tools/logging/start_sim_log_cap.ts:81
+- [x] src/mcp/tools/macos/get_mac_app_path.ts:167
+- [x] src/mcp/tools/project-discovery/get_app_bundle_id.ts:91
+- [x] src/mcp/tools/project-discovery/get_mac_bundle_id.ts:88
+- [x] src/mcp/tools/project-discovery/list_schemes.ts:83
+- [x] src/mcp/tools/project-discovery/show_build_settings.ts:88
+- [x] src/mcp/tools/project-scaffolding/scaffold_ios_project.ts:366
+- [x] src/mcp/tools/project-scaffolding/scaffold_macos_project.ts:340
+- [x] src/mcp/tools/simulator/boot_sim.ts:69
+- [x] src/mcp/tools/simulator/build_run_sim.ts:486
+- [x] src/mcp/tools/simulator/get_sim_app_path.ts:244
+- [x] src/mcp/tools/simulator/install_app_sim.ts:93
+- [x] src/mcp/tools/simulator/launch_app_logs_sim.ts:100
+- [x] src/mcp/tools/simulator/launch_app_sim.ts:127
+- [x] src/mcp/tools/simulator/list_sims.ts:196
+- [x] src/mcp/tools/simulator/open_sim.ts:42
+- [x] src/mcp/tools/simulator/record_sim_video.ts:130

docs/TOOLS-CLI.md

@@ -187,4 +187,4 @@ XcodeBuildMCP provides 71 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-08T12:09:33.648Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-11T19:41:33.286Z UTC*

docs/TOOLS.md

@@ -202,4 +202,4 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-08T12:09:33.648Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-11T19:41:33.286Z UTC*

manifests/tools/boot_sim.yaml

@@ -7,3 +7,19 @@ description: Boot iOS simulator.
 annotations:
   title: Boot Simulator
   destructiveHint: true
+nextSteps:
+  - label: Open the Simulator app (makes it visible)
+    toolId: open_sim
+    priority: 1
+  - label: Install an app
+    toolId: install_app_sim
+    params:
+      simulatorId: ${simulatorId}
+      appPath: PATH_TO_YOUR_APP
+    priority: 2
+  - label: Launch an app
+    toolId: launch_app_sim
+    params:
+      simulatorId: ${simulatorId}
+      bundleId: YOUR_APP_BUNDLE_ID
+    priority: 3

manifests/tools/build_run_sim.yaml

@@ -9,3 +9,13 @@ predicates:
 annotations:
   title: Build Run Simulator
   destructiveHint: true
+nextSteps:
+  - label: Capture structured logs (app continues running)
+    toolId: start_sim_log_cap
+    priority: 1
+  - label: Capture console + structured logs (app restarts)
+    toolId: start_sim_log_cap
+    priority: 2
+  - label: Launch app with logs in one step
+    toolId: launch_app_logs_sim
+    priority: 3

manifests/tools/debug_attach_sim.yaml

@@ -6,3 +6,13 @@ names:
 description: Attach LLDB to sim app.
 routing:
   stateful: true
+nextSteps:
+  - label: Add a breakpoint
+    toolId: debug_breakpoint_add
+    priority: 1
+  - label: Continue execution
+    toolId: debug_continue
+    priority: 2
+  - label: Show call stack
+    toolId: debug_stack
+    priority: 3

manifests/tools/get_app_bundle_id.yaml

@@ -7,3 +7,16 @@ description: Extract bundle id from .app.
 annotations:
   title: Get App Bundle ID
   readOnlyHint: true
+nextSteps:
+  - label: Install on simulator
+    toolId: install_app_sim
+    priority: 1
+  - label: Launch on simulator
+    toolId: launch_app_sim
+    priority: 2
+  - label: Install on device
+    toolId: install_app_device
+    priority: 3
+  - label: Launch on device
+    toolId: launch_app_device
+    priority: 4

manifests/tools/get_device_app_path.yaml

@@ -7,3 +7,13 @@ description: Get device built app path.
 annotations:
   title: Get Device App Path
   readOnlyHint: true
+nextSteps:
+  - label: Get bundle ID
+    toolId: get_app_bundle_id
+    priority: 1
+  - label: Install app on device
+    toolId: install_app_device
+    priority: 2
+  - label: Launch app on device
+    toolId: launch_app_device
+    priority: 3

manifests/tools/get_mac_app_path.yaml

@@ -7,3 +7,10 @@ description: Get macOS built app path.
 annotations:
   title: Get macOS App Path
   readOnlyHint: true
+nextSteps:
+  - label: Get bundle ID
+    toolId: get_mac_bundle_id
+    priority: 1
+  - label: Launch app
+    toolId: launch_mac_app
+    priority: 2

manifests/tools/get_mac_bundle_id.yaml

@@ -7,3 +7,10 @@ description: Extract bundle id from macOS .app.
 annotations:
   title: Get Mac Bundle ID
   readOnlyHint: true
+nextSteps:
+  - label: Launch the app
+    toolId: launch_mac_app
+    priority: 1
+  - label: Build again
+    toolId: build_macos
+    priority: 2

manifests/tools/get_sim_app_path.yaml

@@ -7,3 +7,16 @@ description: Get sim built app path.
 annotations:
   title: Get Simulator App Path
   readOnlyHint: true
+nextSteps:
+  - label: Get bundle ID
+    toolId: get_app_bundle_id
+    priority: 1
+  - label: Boot simulator
+    toolId: boot_sim
+    priority: 2
+  - label: Install app
+    toolId: install_app_sim
+    priority: 3
+  - label: Launch app
+    toolId: launch_app_sim
+    priority: 4

manifests/tools/install_app_sim.yaml

@@ -7,3 +7,10 @@ description: Install app on sim.
 annotations:
   title: Install App Simulator
   destructiveHint: true
+nextSteps:
+  - label: Open the Simulator app
+    toolId: open_sim
+    priority: 1
+  - label: Launch the app
+    toolId: launch_app_sim
+    priority: 2

manifests/tools/launch_app_device.yaml

@@ -7,3 +7,7 @@ description: Launch app on device.
 annotations:
   title: Launch App Device
   destructiveHint: true
+nextSteps:
+  - label: Stop the app
+    toolId: stop_app_device
+    priority: 1

manifests/tools/launch_app_logs_sim.yaml

@@ -9,3 +9,7 @@ routing:
 annotations:
   title: Launch App Logs Simulator
   destructiveHint: true
+nextSteps:
+  - label: Stop capture and retrieve logs
+    toolId: stop_sim_log_cap
+    priority: 1

manifests/tools/launch_app_sim.yaml

@@ -7,3 +7,20 @@ description: Launch app on simulator.
 annotations:
   title: Launch App Simulator
   destructiveHint: true
+nextSteps:
+  - label: Open Simulator app to see it
+    toolId: open_sim
+    priority: 1
+  - label: Capture structured logs (app continues running)
+    toolId: start_sim_log_cap
+    params:
+      simulatorId: ${simulatorId}
+      bundleId: ${bundleId}
+    priority: 2
+  - label: Capture console + structured logs (app restarts)
+    toolId: start_sim_log_cap
+    params:
+      simulatorId: ${simulatorId}
+      bundleId: ${bundleId}
+      captureConsole: true
+    priority: 3

manifests/tools/list_devices.yaml

@@ -7,3 +7,13 @@ description: List connected devices.
 annotations:
   title: List Devices
   readOnlyHint: true
+nextSteps:
+  - label: Build for device
+    toolId: build_device
+    priority: 1
+  - label: Run tests on device
+    toolId: test_device
+    priority: 2
+  - label: Get app path
+    toolId: get_device_app_path
+    priority: 3

manifests/tools/list_schemes.yaml

@@ -7,3 +7,13 @@ description: List Xcode schemes.
 annotations:
   title: List Schemes
   readOnlyHint: true
+nextSteps:
+  - label: Build for macOS
+    toolId: build_macos
+    priority: 1
+  - label: Build for iOS Simulator
+    toolId: build_sim
+    priority: 2
+  - label: Show build settings
+    toolId: show_build_settings
+    priority: 3

manifests/tools/list_sims.yaml

@@ -7,3 +7,25 @@ description: List iOS simulators.
 annotations:
   title: List Simulators
   readOnlyHint: true
+nextSteps:
+  - label: Boot a simulator
+    toolId: boot_sim
+    params:
+      simulatorId: UUID_FROM_ABOVE
+    priority: 1
+  - label: Open the simulator UI
+    toolId: open_sim
+    priority: 2
+  - label: Build for simulator
+    toolId: build_sim
+    params:
+      scheme: YOUR_SCHEME
+      simulatorId: UUID_FROM_ABOVE
+    priority: 3
+  - label: Get app path
+    toolId: get_sim_app_path
+    params:
+      scheme: YOUR_SCHEME
+      platform: iOS Simulator
+      simulatorId: UUID_FROM_ABOVE
+    priority: 4

manifests/tools/open_sim.yaml

@@ -7,3 +7,28 @@ description: Open Simulator app.
 annotations:
   title: Open Simulator
   destructiveHint: true
+nextSteps:
+  - label: Boot a simulator if needed
+    toolId: boot_sim
+    params:
+      simulatorId: UUID_FROM_LIST_SIMS
+    priority: 1
+  - label: Capture structured logs (app continues running)
+    toolId: start_sim_log_cap
+    params:
+      simulatorId: UUID
+      bundleId: YOUR_APP_BUNDLE_ID
+    priority: 2
+  - label: Capture console + structured logs (app restarts)
+    toolId: start_sim_log_cap
+    params:
+      simulatorId: UUID
+      bundleId: YOUR_APP_BUNDLE_ID
+      captureConsole: true
+    priority: 3
+  - label: Launch app with logs in one step
+    toolId: launch_app_logs_sim
+    params:
+      simulatorId: UUID
+      bundleId: YOUR_APP_BUNDLE_ID
+    priority: 4

manifests/tools/record_sim_video.yaml

@@ -9,3 +9,7 @@ routing:
 annotations:
   title: Record Simulator Video
   destructiveHint: true
+nextSteps:
+  - label: Stop and save the recording
+    toolId: record_sim_video
+    priority: 1

manifests/tools/scaffold_ios_project.yaml

@@ -9,3 +9,11 @@ predicates:
 annotations:
   title: Scaffold iOS Project
   destructiveHint: true
+nextSteps:
+  - label: Read the generated README in the workspace root before working on the project
+  - label: Build for simulator
+    toolId: build_sim
+    priority: 1
+  - label: Build and run on simulator
+    toolId: build_run_sim
+    priority: 2

manifests/tools/scaffold_macos_project.yaml

@@ -9,3 +9,11 @@ predicates:
 annotations:
   title: Scaffold macOS Project
   destructiveHint: true
+nextSteps:
+  - label: Read the generated README in the workspace root before working on the project
+  - label: Build for macOS
+    toolId: build_macos
+    priority: 1
+  - label: Build and run on macOS
+    toolId: build_run_macos
+    priority: 2

manifests/tools/show_build_settings.yaml

@@ -9,3 +9,13 @@ predicates:
 annotations:
   title: Show Build Settings
   readOnlyHint: true
+nextSteps:
+  - label: Build for macOS
+    toolId: build_macos
+    priority: 1
+  - label: Build for iOS Simulator
+    toolId: build_sim
+    priority: 2
+  - label: List schemes
+    toolId: list_schemes
+    priority: 3

manifests/tools/snapshot_ui.yaml

@@ -4,6 +4,21 @@ names:
   mcp: snapshot_ui
   cli: snapshot-ui
 description: Print view hierarchy with precise view coordinates (x, y, width, height) for visible elements.
+nextSteps:
+  - label: Refresh after layout changes
+    toolId: snapshot_ui
+    params:
+      simulatorId: ${simulatorId}
+  - label: Tap on element
+    toolId: tap
+    params:
+      simulatorId: ${simulatorId}
+      x: 0
+      y: 0
+  - label: Take screenshot for verification
+    toolId: screenshot
+    params:
+      simulatorId: ${simulatorId}
 annotations:
   title: Snapshot UI
   readOnlyHint: true

manifests/tools/start_device_log_cap.yaml

@@ -9,3 +9,7 @@ routing:
 annotations:
   title: Start Device Log Capture
   destructiveHint: true
+nextSteps:
+  - label: Stop capture and retrieve logs
+    toolId: stop_device_log_cap
+    priority: 1

manifests/tools/start_sim_log_cap.yaml

@@ -9,3 +9,7 @@ routing:
 annotations:
   title: Start Simulator Log Capture
   destructiveHint: true
+nextSteps:
+  - label: Stop capture and retrieve logs
+    toolId: stop_sim_log_cap
+    priority: 1

src/core/manifest/__tests__/schema.test.ts

@@ -40,6 +40,7 @@ describe('schema', () => {
       if (result.success) {
         expect(result.data.availability).toEqual({ mcp: true, cli: true });
         expect(result.data.predicates).toEqual([]);
+        expect(result.data.nextSteps).toEqual([]);
       }
     });
 
@@ -201,6 +202,7 @@ describe('schema', () => {
         names: { mcp: 'build_sim', cli: 'build-simulator' },
         availability: { mcp: true, cli: true },
         predicates: [],
+        nextSteps: [],
       };
 
       expect(getEffectiveCliName(tool)).toBe('build-simulator');
@@ -213,6 +215,7 @@ describe('schema', () => {
         names: { mcp: 'build_sim' },
         availability: { mcp: true, cli: true },
         predicates: [],
+        nextSteps: [],
       };
 
       expect(getEffectiveCliName(tool)).toBe('build-sim');