6 files changed
+116
-7
docs/controlkit.md
new
+97
@@ -0,0 +1,97 @@
1
+# ControlKit runners
2
+
3
+ControlKit is the native XCTest runner used by the CLI's Apple-platform MCP
4
+tools. The public runner project is
5
+[`xcrs-controlkit`](https://github.com/ondeinference/xcrs-controlkit). It uses
6
+one Xcode project generated by XcodeGen, with platform-specific targets and
7
+schemes:
8
+
9
+| Platform | Scheme | App product |
10
+| --- | --- | --- |
11
+| iOS / iPadOS | `ControlKit-iOS` | `ControlKit.app` |
12
+| tvOS | `ControlKit-tvOS` | `ControlKit.app` |
13
+| visionOS | `ControlKit-visionOS` | `ControlKit.app` |
14
+| watchOS | `ControlKit-watchOS` | `ControlKit.app` |
15
+| macOS | `ControlKit-macOS` | `ControlKit.app` |
16
+
17
+The scheme and target names keep their platform suffixes so Xcode can select
18
+the correct SDK, while each built app is named `ControlKit`.
19
+
20
+## Build a runner
21
+
22
+Install XcodeGen once, clone the runner project, and generate the Xcode
23
+project:
24
+
25
+```sh
26
+brew install xcodegen
27
+cd <path-to-xcrs-controlkit>/Runners
28
+xcodegen generate
29
+```
30
+
31
+Build the simulator runner for the platform you need:
32
+
33
+```sh
34
+xcodebuild -project XCRSControlKitRunner.xcodeproj \
35
+ -scheme ControlKit-<platform> \
36
+ -destination 'generic/platform=<platform> Simulator' \
37
+ build-for-testing
38
+```
39
+
40
+Replace `<platform>` with `iOS`, `tvOS`, `watchOS`, or `visionOS`. macOS is
41
+built with `-destination 'platform=macOS'` and runs on the local Mac rather
42
+than a simulator.
43
+
44
+## Start the runner
45
+
46
+Boot a compatible simulator and run the UI-test host:
47
+
48
+```sh
49
+xcodebuild -project XCRSControlKitRunner.xcodeproj \
50
+ -scheme ControlKit-<platform> \
51
+ -destination 'id=<simulator-udid>' \
52
+ test-without-building
53
+```
54
+
55
+The shared XCTest runner starts a local ControlKit JSON-RPC server on
56
+`127.0.0.1:12004`. Keep that test process running while calling the MCP tools.
57
+The macOS UI-test target includes the network-server entitlement required to
58
+bind the local port.
59
+
60
+## Connect through `smb --mcp`
61
+
62
+Start the CLI MCP server:
63
+
64
+```sh
65
+smb --mcp
66
+```
67
+
68
+The runner tools accept either `simulator_name` or `simulator_udid`. The
69
+standalone `xcrs --mcp` server exposes the same tools with the `xcrs_` prefix.
70
+
71
+| Tool | Runner | Purpose |
72
+| --- | --- | --- |
73
+| `smb_controlkit_capabilities` | All platforms | Read platform and capability information. |
74
+| `smb_macos_click` | macOS | Click at screen coordinates. |
75
+| `smb_visionos_spatial_tap` | visionOS | Perform a spatial tap. |
76
+| `smb_watchos_tap` | watchOS | Perform a touch tap. |
77
+| `smb_simulator_tap` | iOS / tvOS | Perform a touch tap. |
78
+| `smb_simulator_type_text` | iOS / tvOS | Type into the focused field. |
79
+| `smb_simulator_swipe` | iOS / tvOS | Swipe between coordinates. |
80
+| `smb_simulator_screenshot` | All simulator runners | Capture a PNG screenshot. |
81
+| `smb_simulator_ui_dump` | All UI-test runners | Read the accessibility hierarchy. |
82
+
83
+For a local macOS runner, omit simulator fields and pass `host` and
84
+`controlkit_port` when needed:
85
+
86
+```json
87
+{
88
+ "host": "127.0.0.1",
89
+ "controlkit_port": 12004,
90
+ "x": 400,
91
+ "y": 300
92
+}
93
+```
94
+
95
+Platform-specific operations intentionally reject unsupported input. For
96
+example, visionOS rejects raw touch, watchOS rejects pointer and spatial input,
97
+and macOS rejects touch and Home-button requests.
docs/interfaces.md
+4
-3
@@ -50,8 +50,8 @@ dialog under `--tui`; in the headless interface they ask inline instead.
50
51
`smb --mcp` starts an MCP (Model Context Protocol) server that speaks
52
JSON-RPC over stdio. Instead of running a single command and exiting, it stays
53
-up and exposes smbCloud operations — 30 tools spanning accounts, projects,
54
-tenants, Mail, and Auth — as MCP **tools** that an MCP-capable client
53
+up and exposes 50 tools spanning accounts, projects, tenants, Mail, Auth,
54
+simulators, and ControlKit runners as MCP **tools** that an MCP-capable client
55
(Claude Desktop, Claude Code, Cursor, or any other assistant/agent) can call.
56
The subcommand is ignored in this mode.
57
@@ -61,4 +61,5 @@ including the `*_delete` tools, which apply immediately with no confirmation
61
prompt.
62
63
For the client setup guide and the full tool reference, see
64
-[MCP Server](./mcp.md).
64
+[MCP Server](./mcp.md). For running the native Apple-platform runners, see
65
+[ControlKit runners](./controlkit.md).
docs/mcp.md
+2
@@ -13,6 +13,8 @@ compares to the CLI's other two interfaces (headless and `--tui`), see
13
[Interfaces](./interfaces.md). The server is also listed in the official MCP
14
Registry as `io.github.smbcloudXYZ/smbcloud-cli`, so clients that browse the
15
registry can install it for you — see [MCP Registry](./mcp-registry.md).
16
+For building and starting the native runners, see
17
+[ControlKit runners](./controlkit.md).
18
19
## Prerequisites
20
website/.gitignore
+1
@@ -44,6 +44,7 @@ yarn-error.log*
44
/content/developer/cli/pypi.mdx
45
/content/developer/cli/interfaces.mdx
46
/content/developer/cli/mcp.mdx
47
+/content/developer/cli/controlkit.mdx
48
/content/developer/cli/ci.mdx
49
/content/developer/contributing/_meta.js
50
/content/developer/contributing/debugging.mdx
website/content/developer/cli/index.mdx
+4
-3
@@ -7,8 +7,8 @@ description: Install the smbCloud CLI (smb), run it headless/--tui/--mcp, and co
7
# CLI
8
9
`smb` is the smbCloud command-line tool. You use it to log in and to manage and
10
-deploy your smbCloud resources — projects, tenants, Mail, and Auth — from the
11
-terminal, a script, or an MCP-connected AI agent.
10
+deploy your smbCloud resources — projects, tenants, Mail, Auth, simulators, and
11
+ControlKit runners — from the terminal, a script, or an MCP-connected AI agent.
12
13
```text
14
Usage: smb [OPTIONS] [COMMAND]
@@ -62,7 +62,8 @@ You can also download a binary for any release directly from the
62
| Guide | What it covers |
63
| --- | --- |
64
| [Interfaces](/developer/cli/interfaces) | The three ways `smb` runs — headless, `--tui`, and `--mcp` — and when to use each. |
65
-| [MCP Server](/developer/cli/mcp) | Connect Claude Desktop, Claude Code, Cursor, or any MCP client to `smb --mcp`; the full 30-tool reference. |
65
+| [MCP Server](/developer/cli/mcp) | Connect Claude Desktop, Claude Code, Cursor, or any MCP client to `smb --mcp`; the full tool reference. |
66
+| [ControlKit runners](/developer/cli/controlkit) | Build native iOS, tvOS, visionOS, watchOS, and macOS runners and expose them through the MCP servers. |
67
| [CI](/developer/cli/ci) | Run `smb` non-interactively with `--ci` and deploy from GitHub Actions. |
68
69
import { Callout } from 'nextra/components'
website/scripts/generate-developer-docs.mjs
+8
-1
@@ -69,7 +69,14 @@ const MANIFEST = {
69
slug: 'mcp',
70
title: 'MCP Server',
71
description:
72
- 'Run the smbCloud CLI as an MCP server and connect Claude Desktop, Claude Code, Cursor, or any MCP client to manage your projects, tenants, Mail, and Auth apps. Setup guide plus the full 30-tool reference.'
72
+ 'Run the smbCloud CLI as an MCP server and connect Claude Desktop, Claude Code, Cursor, or any MCP client to manage smbCloud resources, simulators, and ControlKit runners. Setup guide plus the full tool reference.'
73
+ },
74
+ {
75
+ src: 'controlkit.md',
76
+ slug: 'controlkit',
77
+ title: 'ControlKit runners',
78
+ description:
79
+ 'Build and connect the native ControlKit runners for iOS, tvOS, visionOS, watchOS, and macOS through the smbCloud and xcrs MCP servers.'
80
},
81
{
82
src: 'ci.md',