macwright-dev

MacWright MCP Server Development

Project Structure

macwright/
├── src/
│   ├── index.ts          — Server entry, registers all tools
│   └── tools/
│       ├── mouse.ts      — click, double_click, right_click, move_mouse, get_mouse_position, drag
│       ├── keyboard.ts   — type_text, press_key
│       ├── screenshot.ts — screenshot (supports x,y,width,height region capture)
│       ├── screen.ts     — get_screen_size
│       ├── scroll.ts     — scroll
│       ├── shell.ts      — run_shell (spawn-based, supports stdin input, timeout, cwd)
│       ├── safari.ts     — safari_url, safari_js, safari_navigate_back, safari_reload,
│       │                   scroll_page, find_element, click_element, wait_for_element,
│       │                   get_page_text, fill_form, get_element_attr, screenshot_element,
│       │                   safari_tabs
│       ├── clipboard.ts  — get_clipboard, set_clipboard
│       ├── applescript.ts — run_applescript
│       ├── notification.ts — send_notification
│       └── wait.ts       — wait
├── src/utils/
│   ├── exec.ts           — execCommand helper
│   └── capture.ts        — afterAction (wait + screenshot chaining)
└── dist/                 — Compiled JS (auto-generated)

Build & Test Workflow

npm run build   # TypeScript → dist/

CRITICAL: After npm run build, the MCP server process must be restarted to pick up new tools. The server runs from dist/index.js — changes only take effect after restart + rebuild. The Claude Code IDE integration will restart on reconnect.

To verify a new tool works: use run_applescript to test the underlying AppleScript first (no restart needed), then rebuild and use the actual MCP tool after restart.

Adding a New Tool

1. Find the appropriate src/tools/*.ts file (or create one)
2. Add server.registerTool(name, schema, handler) call
3. Export the registration function from the file
4. Import and call it in src/index.ts if new file
5. npm run build
6. Test via AppleScript equivalent first to validate logic