home-screen-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HOMESCREEN_DATA | No | Local directory for drafts, caches and layout backups. | /tmp/screen-organizer-inspection |
| HOMESCREEN_READ_ONLY | No | Use 1 for layout reads and local draft editing. | 1 |
| HOMESCREEN_ALLOW_APPLY | No | Use 1 with HOMESCREEN_READ_ONLY=0 for explicitly requested Apply and Restore. | 0 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Arrange an iPhone Home Screen. Workflow: read_phone -> show_layout -> edit the draft (arrange / move / create_folder / sort_* / file_into_folders ...) -> diff -> render_preview -> apply only when the user explicitly asks. Every edit is one undo step (undo / redo). Item ids: apps use their bundle id; folders and widgets use folder:N / widget:N. Targets: 'dock', 'library', 'bank' (a holding tray; empty it before applying), 'page:N' (1-based; N = last+1 makes a new page), 'folder:[:N]'. To take an app off the Home Screen, move it to 'library' (App Library only). Leaving it out does NOT work: iOS puts it back. Pages hold 24 slots (6 rows x 4 columns); widgets take small=2x2, medium=4x2, large=4x4. place_at puts an item in an exact spot, leaving gaps; any move drops that. iOS doesn't report gaps made on the phone over USB, so those close on apply. Folders hold 9 per page. Leave page 1 and the dock alone unless asked: they are muscle memory. To sort by color, call icon_colors first; get_icons only for the few you can't judge.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| read_phoneA | Read the Home Screen from the connected iPhone and start a fresh draft from it. Discards any unapplied draft. |
| show_layoutB | The current draft: dock, every page and the App Library-only apps, as {id, name} items (folders carry their contents, widgets their size). |
| find_appsC | Find items by name or bundle id substring. |
| icon_colorsA | Dominant icon color per app (family, background, hex, hue 0-360). Omit ids for every app. |
| get_iconsB | Icon images for up to 24 apps, in the order given. |
| arrangeA | Set the whole top-level layout at once. pages = list of pages, each a list of ids in order (row by row). library = apps kept only in the App Library. Every top-level item and library app must appear exactly once. dock / library omitted = unchanged. |
| moveA | Move one item to target ('dock', 'library', 'page:N', 'folder:[:N]'), at index
(0-based, default end) or just before the item with id |
| create_folderC | Make a folder at target/index holding item_ids (in order). |
| rename_folderC | Rename a folder. |
| dissolve_folderC | Remove a folder, putting its apps where it was. |
| file_into_foldersA | File loose apps into folders: {folder name: [app ids]}. Apps join an existing folder with that name, or a new folder (2+ apps). Apps on page 1 are left alone by default. |
| sort_by_colorA | Rainbow-sort loose apps (red -> purple, then white/gray/black). Folders and widgets go first. Page 1 is left alone by default. |
| sort_alphabeticallyC | A-Z sort of folders and loose apps. Page 1 is left alone by default. |
| sort_folder_contentsC | A-Z inside every folder. |
| app_store_categoriesA | App Store genre per app (Apple apps are 'Apple'). This sends the bundle ids to Apple's public lookup API, so only call it when the user is fine with that. Cached locally. |
| place_atB | Put an item in an exact spot (row 1-6, column 1-4) on a page, leaving empty spaces around it, like dragging it to an empty spot on the iPhone. Other items flow around it. |
| close_gapsC | Let placed items flow with the rest again (removes their gaps). |
| swapC | Trade the places of two items. |
| screen_timeB | Which apps get used, the top apps with where they are now, and estimated page swipes for
the device vs the draft. source='device': the device's own memory reports (no setup; apps iOS
keeps running for calls or in memory every day count less, listed under 'background');
source='mac': Screen Time synced to this Mac (Share Across Devices), last |
| optimize_by_usageB | Most-used apps and folders onto the earliest pages, most-used apps onto each folder's first page (usage from screen_time, else the device's memory reports, else Screen Time). Widgets keep their pages; dock and App Library untouched. |
| page_opA | Page operations: op='insert' (new empty page at |
| remove_emptyB | Drop empty pages and empty folders from the draft. |
| undoB | Undo the last draft edit. |
| redoA | Redo the last undone draft edit. |
| reset_draftA | Throw away draft edits and go back to the layout as read from the phone (undoable). |
| diffA | What applying the draft would change, any problems, and the apply_token. |
| render_previewA | Write an HTML preview (draft vs phone, moved icons outlined) and return its path. |
| applyA | Write the draft to the iPhone. Only call when the user explicitly asked to apply this draft. Needs the apply_token from the latest diff. Backs up first and verifies after. |
| list_backupsB | Layouts saved before each apply/restore, oldest first. |
| restoreC | Write a backup to the iPhone. Only when the user explicitly asked. Same gate as apply. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 30 tools
Most tools target a clearly distinct operation: read_phone vs show_layout vs diff vs apply form a coherent draft lifecycle, and the sorting/moving tools are well differentiated by description. Minor overlap remains between read_phone and reset_draft (both discard edits, one re-reads the device) and between arrange/place_at/swap as different granularities of the same move action.
The set is overwhelmingly snake_case verb_noun or verb (move, swap, apply, create_folder, sort_by_color, list_backups). A handful of tools are noun-only or bare nouns (icon_colors, screen_time, page_op, app_store_categories, diff), which breaks the pattern slightly but stays readable and predictable.
At 30 tools this is well past the heavy threshold for a single domain, and several could be consolidated (three sort_* tools, place_at/swap/close_gaps, undo/redo/reset_draft). Individual tools are meaningful, but the surface is large enough that an agent must scan a lot to pick correctly.
Coverage is strong: read, inspect, diff, preview, apply with token gating, backup listing, restore, undo/redo, and full folder/page/item manipulation are all present. Gaps are minor — no tool to add/remove/edit widgets themselves, and no way to pick or prune a specific backup beyond restore and list_backups.