Sidecar Onestep

SidecarOneStep / 随航一步

English | 中文

<a name="english"></a>

Overview

SidecarOneStep is a powerful macOS Sidecar enhancement tool that makes managing iPad connections effortless. Through MCP (Model Context Protocol) integration, AI assistants like Claude, Cursor, and OpenClaw can directly control your Sidecar connections.

📋 System Requirements

⚠️ Prerequisites: Both Mac and iPad must be signed into the same iCloud account with 2FA enabled.

🌟 Key Features

• 🚀 One-Click Connection - Instantly connect/disconnect iPad from menu bar
• 📱 Remote Control - Web console for controlling Sidecar from your phone
• 🔌 Wired Mode - Force wired connection for low-latency stability
• 🖥️ Virtual Display - Create virtual displays for extended workspace (v1.4.0+)
• 🛠️ Full Automation - Complete REST API + MCP integration (15 tools)
• 🤖 AI Integration - Let AI assistants manage your connections

📥 Installation

1. Download & Install App

Download the latest version from GitHub Releases:

https://github.com/yi-nology/sidecarOneStep/releases/latest

Or direct download:

curl -L -o SidecarOneStep.dmg https://github.com/yi-nology/sidecarOneStep/releases/download/v1.3.9/SidecarOneStep_Installer.dmg
hdiutil attach SidecarOneStep.dmg
cp -R /Volumes/SidecarOneStep\ Installer/SidecarOneStep.app /Applications/

2. Enable MCP in Settings

1. Open SidecarOneStep
2. Go to "Settings" → "Developer / Integrations"
3. Enable "MCP (stdio)"

3. Configure MCP

# Add SidecarOneStep to mcporter
mcporter config add sidecar-onestep \
  --command /Applications/SidecarOneStep.app/Contents/MacOS/SidecarOneStep \
  --args mcp

# Verify configuration
mcporter list sidecar-onestep

Expected output:

sidecar-onestep — macOS Sidecar 增强工具 (10 tools)

🚀 Quick Start

Prerequisites Check

Before using this skill, ensure:

• SidecarOneStep.app installed in /Applications/
• MCP enabled in app settings (Settings → Developer/Integrations → MCP)
• mcporter configured: mcporter list sidecar-onestep should show the server
• iPad nearby, unlocked, and on same iCloud account

List Available Devices

mcporter call sidecar-onestep.list_devices

Response:

["张易的iPad Pro", "iPad Air"]

Connect Device (Recommended: Async)

# Async connection (non-blocking, recommended)
mcporter call sidecar-onestep.connect_device_async device_name="张易的iPad Pro" wired=true

# Response:
{
  "id": "job_12345",
  "status": "success",
  "result": "张易的iPad Pro",
  "wired": true
}

Disconnect Device

mcporter call sidecar-onestep.disconnect_device device_name="张易的iPad Pro"

Get Status

mcporter call sidecar-onestep.get_status

Response:

{
  "active_device": "张易的iPad Pro",
  "active_wired": true,
  "server_running": true,
  "server_port": 8765
}

🛠️ Available Tools (15)

🔔 Trigger Examples (for AI Assistants)

When a user says any of the following, this skill should be activated:

Example 1: Connect iPad

User: "Connect my iPad"
User: "用有线模式连我的 iPad"

→ AI calls: connect_device_async device_name="<device_name>" wired=true

Example 2: Check Status

User: "Is my iPad connected?"
User: "看看 Sidecar 状态"

→ AI calls: get_status

Example 3: Disconnect

User: "Disconnect iPad"
User: "断开 iPad 连接"

→ AI calls: disconnect_device device_name="<device_name>"

Example 4: Web Console

User: "Start the Sidecar web console"
User: "打开 Sidecar 远程控制台"

→ AI calls: start_http_server port=8765

Example 5: List Devices

User: "Show me available Sidecar devices"
User: "列出可用的 iPad"

→ AI calls: list_devices

🎯 Use Cases

Daily Workflow

# 1. Connect iPad (async, non-blocking)
mcporter call sidecar-onestep.connect_device_async device_name="iPad Pro" wired=true

# 2. Start web console
mcporter call sidecar-onestep.start_http_server port=8765

# 3. Check status
mcporter call sidecar-onestep.get_status

Meeting Mode (Wireless)

# Wireless connection for mobility
mcporter call sidecar-onestep.connect_device_async device_name="iPad Air" wired=false

Automation Integration

# Use in scripts, Shortcuts, Raycast, Alfred, etc.
mcporter call sidecar-onestep.connect_device_async device_name="iPad Pro" wired=true

🤖 AI Assistant Integration

SidecarOneStep works seamlessly with AI assistants:

Natural Language Commands:

• "List my iPad devices" → list_devices
• "Connect to iPad Pro" → connect_device_async
• "Connect iPad with wired mode" → connect_device_async wired=true
• "Disconnect iPad" → disconnect_device
• "Start web console" → start_http_server
• "Check Sidecar status" → get_status

🔧 Troubleshooting

Issue: Device list is empty

Solution:

1. Ensure iPad and Mac use the same iCloud account
2. Ensure iPad supports Sidecar (2018 or later)
3. Ensure iPad is nearby and unlocked
4. Check "System Preferences" → "Sidecar"

Issue: Async connection job not found

Note: In stdio MCP mode, each call creates a new process. Use connect_device_async which now returns the complete status immediately, no need to call get_job_status.

Issue: MCP server not responding

Solution:

1. Verify app is installed: ls /Applications/SidecarOneStep.app
2. Check configuration: mcporter list sidecar-onestep
3. Restart mcporter daemon: mcporter daemon restart