TuriX MCP Server for Automated Preset Workflows

Overview

TuriX MCP Server provides a lightweight, locally hosted Model Context Protocol (MCP) server designed to automate preset workflows on macOS. It lets developers and power users script and orchestrate pre-setting tasks — launching apps, adjusting system settings, preparing project folders, and running shell commands — through a consistent API. The server acts as a bridge between higher-level “presets” or workflows and low-level system actions, enabling repeatable and reliable setup before you start work.

Because the MCP server centralizes context-aware actions, it’s useful for reproducible environments (development setups, demo booths, lab machines), automated onboarding, or integrating with LLM-based assistants that need to perform deterministic, auditable tasks on a host machine. The macOS branch (mac_mcp) contains mac-specific adapters and examples for interacting with system services and GUI automation.

Features

• Exposes a RESTful JSON API for executing named presets and ad-hoc tasks
• Built-in adapters for common macOS actions (apps, shell, filesystem, AppleScript)
• Preset definition format for repeatable multi-step workflows
• Local-first execution for privacy and low latency — no external cloud required
• Logging and dry-run support for safe testing of presets
• Configurable security and permission controls for macOS TCC and automation needs
• Integration-friendly: can be called from scripts, CI, or AI agents

Installation / Configuration

Prerequisites:

• macOS (for mac_mcp branch)
• Python 3.10+ (or the version specified in repository)
• Git

Clone the macOS branch:

git clone https://github.com/TurixAI/TuriX-CUA.git
cd TuriX-CUA
git checkout mac_mcp

Create a virtual environment and install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

• Copy the example config and edit environment-specific values:

cp config.example.yaml config.yaml
# edit config.yaml to set server port, log level, and allowed clients

Start the server:

# from project root
python -m turix_mcp.server --config config.yaml

By default the server listens on localhost and requires a token defined in the config for API calls. Use a firewall or socket-level filtering if you expose the server beyond localhost.

Example minimal config structure (config.yaml):

server:
  host: 127.0.0.1
  port: 8080
  api_token: "replace-with-secure-token"

logging:
  level: INFO

permissions:
  allow_shell: true
  allow_apple_script: true
  allowed_apps: ["Terminal", "Visual Studio Code"]

Available Tools / Resources

The mac_mcp branch includes several tool adapters. Typical categories:

Refer to the repository’s /tools and /presets directories for concrete implementations and examples.

Use Cases

1. Project bootstrap (developer)

• Create a new project folder, initialize a git repo, open VS Code, start the dev server.
• Preset steps:
  • filesystem: create directories and README
  • shell: git init, npm install
  • app_control: open VS Code at project path

2. Demo booth setup (presenters)

• Switch display arrangement, open a specific browser profile, load presentation slides and enable Do Not Disturb.
• Preset steps:
  • shell/apple_script: adjust display via systemtools
  • app_control: launch browser with profile
  • shell: osascript to toggle DND

3. First-day onboarding (IT automation)

• Configure user environment: map network shares, install required apps, apply company dotfiles.
• Preset steps:
  • filesystem: copy dotfiles
  • shell: run installer scripts
  • app_control: perform initial app launches for first-run setups

Example API call to execute a preset (replace token and URL per your config):

curl -X POST http://127.0.0.1:8080/v1/presets/run \
  -H "Authorization: Bearer replace-with-secure-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo_setup", "dry_run": false, "context": {"project": "demo"}}'

Security & macOS Notes

• Grant Accessibility and Screen Recording permissions for GUI automation and app control (System Preferences → Security & Privacy → Privacy).
• Be cautious with shell execution; prefer least-privilege and use dry-run mode for testing.
• Keep the API bound to localhost or protected by a strong token. If remote access is required, put it behind an authenticated and encrypted reverse proxy.

Troubleshooting

• Permissions errors: verify macOS TCC permissions and restart affected apps.
• Port in use: change port in config.yaml or free the port.
• Logs: increase logging level in config to DEBUG to view detailed step execution.

For source, examples, and contribution guidelines, see the project on GitHub: https://github.com/TurixAI/TuriX-CUA/tree/mac_mcp.