Apple Style MCP Server
Provides Apple Human Interface Guidelines compliance auditing, design-token extraction, cross-platform UI pattern comparison, and production component scaffolding for Apple platform apps.
Audits and scaffolds iOS interfaces against Apple HIG, including safe-area and Dynamic Island handling, 44pt touch targets, Liquid Glass materials, and iOS navigation/tab-bar patterns.
Audits and scaffolds macOS desktop interfaces against Apple HIG, including zero-shift sidebars, titlebar and traffic-light geometry, command palette patterns, and window chrome/safe-area rules.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Apple Style MCP Server Audit my macOS sidebar for HIG compliance and export the design tokens"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π Apple Style MCP Server (@ahmad/apple-style-mcp)
Enterprise-Grade Model Context Protocol (MCP) Server untuk Audit Arsitektur, Design Tokens, dan Scaffolding Komponen Produksi Berbasis Apple Human Interface Guidelines (HIG) Lintas macOS, iPadOS, dan iOS
π Mengapa Proyek Ini Dibuat?
Membangun aplikasi lintas perangkat Apple (macOS Desktop, iPadOS Tablet, dan iOS Mobile) menggunakan teknologi modern (Tauri v2, React + TypeScript, maupun SwiftUI) sering kali mengalami inkonsistensi ergonomi dan visual:
Ikon sidebar yang bergeser (layout shift) saat diciutkan di macOS.
Bayangan (box-shadow) menu yang terpotong bingkai jendela frameless
12pxatau memicu garis hitam1pxpada Windows DWM.Penggunaan material Liquid Glass (iOS 26 / iPadOS 26 / macOS Tahoe) yang keliru diterapkan pada layer konten.
Ukuran target sentuh di bawah
44x44ptatau ketiadaanviewport-fit=cover&env(safe-area-inset-*)di sekitar Dynamic Island dan Home Indicator.
@ahmad/apple-style-mcp hadir sebagai Single Source of Truth bagi AI Coding Agents (Claude Desktop, Cursor, Windsurf, Antigravity) untuk secara otomatis mengaudit proyek, mengekstrak design tokens multi-format, membandingkan pola UI lintas perangkat, dan men-scaffold 21 komponen siap produksi.
Related MCP server: hig-mcp
ποΈ Arsitektur Sistem
flowchart LR
subgraph Client["AI Coding Assistants"]
A1["Claude Desktop"]
A2["Cursor / Windsurf"]
A3["Antigravity IDE"]
end
subgraph Transport["MCP Server Layer"]
SDK["@modelcontextprotocol/sdk<br/>JSON-RPC 2.0 Stdio"]
LOG["Structured JSON Logger<br/>(PII & Path Redaction)"]
SHUT["Graceful Shutdown<br/>(SIGTERM / In-Flight Drain)"]
end
subgraph Core["Apple HIG Domain Engine"]
PROF["Platform Profiles<br/>macOS Β· iPadOS Β· iOS"]
TOK["Token Engine<br/>Liquid Glass & Classic"]
KB["HIG Knowledge Base<br/>13 Topics & 6 Pattern Matrices"]
AUD["Multi-Platform Audit Engine<br/>+ Auto Platform Detector"]
COMP["Component Registry<br/>21 Production Templates"]
end
subgraph Output["Multi-Format Renderers"]
R1["CSS Variables + Safe Area"]
R2["JSON Schema Tokens"]
R3["TypeScript as const"]
R4["SwiftUI Color & Font"]
end
Client <-->|stdio| SDK
SDK --> LOG
SDK --> SHUT
SDK --> PROF
PROF --> TOK
PROF --> KB
PROF --> AUD
PROF --> COMP
TOK --> R1
TOK --> R2
TOK --> R3
TOK --> R4π Matriks Ergonomi & Geometri Multi-Platform Apple HIG
Dimensi Desain | π₯οΈ macOS ( | π± iPadOS ( | π± iOS ( |
Referensi OS | macOS 26 Tahoe / Sonoma | iPadOS 26 | iOS 26 |
Paradigma Navigasi | Zero-Shift Collapsible Sidebar ( | Adaptive Split View (2/3 Kolom, Sidebar | Liquid Glass Floating Tab Bar ( |
Modalitas Input | Pointer presisi + Keyboard + Trackpad | Multi-Touch + Apple Pencil + Trackpad Pointer (Magnetic Hover) + Keyboard | Multi-Touch + Haptic Touch |
Target Sentuh Minimum |
|
|
|
Ukuran Font Body / Large Title |
|
|
|
Window Chrome & Safe Area | Frameless Window ( | Stage Manager Resizable Window + Safe Area Insets | Edge-to-Edge ( |
Aturan Material Liquid Glass | Sidebar, Titlebar, Command Palette, Toast | Split View Sidebar, Floating Tab Bar, Popover | Floating Tab Bar, Navigation Bar, Bottom Sheet |
π Quick Start
Prasyarat
Node.js
>= 22.12.0(direkomendasikan Node.js 24 LTS)npm
>= 10.0.0
Instalasi & Build
# 1. Clone repositori
git clone https://github.com/ahmadeko2017/apple-style-mcp.git
cd apple-style-mcp
# 2. Instal seluruh dependensi
npm install
# 3. Build ke direktori dist/
npm run buildIntegrasi dengan AI Client (mcp_config.json / claude_desktop_config.json)
{
"mcpServers": {
"apple-style-mcp": {
"command": "node",
"args": ["/absolute/path/to/apple-style-mcp/dist/index.js"]
}
}
}π οΈ Dokumentasi Tools MCP (6 Primary Tools + 3 Legacy Aliases)
1. audit_apple_project (Alias v1: audit_desktop_project)
Mengaudit direktori proyek secara statis dan non-destruktif terhadap standar Apple HIG lintas macos, ipados, dan ios (mendukung deteksi platform otomatis).
Parameter Input:
Nama | Tipe | Wajib | Deskripsi |
|
| Tidak | Path direktori proyek yang diaudit (default: direktori aktif) |
|
| Tidak | Target platform yang diaudit (jika kosong, otomatis dideteksi dari proyek) |
Contoh Output:
{
"projectPath": "/workspace/my-apple-app",
"targetPlatforms": ["macos", "ipados", "ios"],
"complianceScore": "100%",
"platformScores": {
"macos": "100%",
"ipados": "100%",
"ios": "100%"
},
"totalChecks": 14,
"passedChecks": 14,
"failedChecks": 0
}2. scaffold_apple_component (Alias v1: scaffold_macos_component)
Menghasilkan kode komponen React + TypeScript produksi siap pakai (21 komponen tersedia):
Kategori | Nama Komponen ( | Deskripsi |
macOS Desktop |
| Tombol kontrol jendela merah/kuning/hijau dengan simbol mikro SVG saat hover |
| Titlebar | |
| Collapsible sidebar ( | |
| Modal Spotlight | |
| Banner notifikasi kanan atas bergaya macOS dengan aturan Zero-Shadow | |
| Panel detail slide-out kanan dengan scroll terisolasi | |
| Utilitas penonaktifan klik kanan browser bawaan pada elemen non-input | |
| Pemformat token | |
iPadOS Tablet |
| Tata letak Split View 2/3 kolom ( |
| Navigasi yang otomatis bertransformasi dari Sidebar ( | |
| Popover kontekstual Liquid Glass bebas bayangan luar | |
| Tombol dengan efek magnetik kursor trackpad iPadOS ( | |
iOS Mobile |
| Floating Capsule Tab Bar iOS 26 yang menyusut otomatis saat scroll ke bawah |
| Navigation Bar dengan Large Title ( | |
| Modal Bottom Sheet dengan detents | |
| Daftar bergaya Inset Grouped iOS dengan radius | |
| Segmented control berlapis dengan indikator tab aktif | |
Universal / Shared |
| Shell aplikasi universal yang merender navigasi sesuai proporsi macOS, iPadOS, atau iOS |
| Detektor | |
| Pembungkus root dengan tinggi | |
| Kontainer permukaan Liquid Glass khusus layer navigasi dengan specular highlight border |
3. get_design_tokens
Mengekstrak design tokens resmi dalam 4 format output:
format:"css"|"json"|"typescript"|"swift"(ekstensi SwiftUIColor,Font, &Layout)platform:"macos"|"ipados"|"ios"design_era:"liquid_glass"(default) |"classic"palette_mode:"apple_system"(default) |"brand_custom"accent_primary: Kode warna hex kustom (misal"#0284c7")
4. scaffold_apple_app_template (Alias v1: scaffold_base_app_template)
Menghasilkan konfigurasi awal proyek (src-tauri/tauri.conf.json, src/styles/tokens.css, serta index.html dengan viewport-fit=cover apabila menyertakan target ios/ipados). Dilengkapi pengaman dry_run: true dan overwrite: false.
5. get_apple_hig_rule
Lookup penjelasan teknis dan formula matematika untuk 13 topik Apple HIG:
zero_shift_geometry, zero_shadow_popovers, window_frame_canvas, titlebar_controls, spotlight_command_palette, toast_banner, liquid_glass_materials, touch_and_hit_targets, safe_area_and_viewport, ipad_split_view_and_morphing, ipad_pointer_and_stage_manager, ios_floating_tab_bar, ios_large_title_and_sheets.
6. compare_platform_pattern
Menghasilkan matriks JSON perbandingan implementasi pola UI antara macOS, iPadOS, dan iOS untuk topik:
navigation, modality, context_actions, notifications, window_and_safe_area, dan typography_and_ergonomics.
π Daftar MCP Resources
URI Resource | MIME Type | Deskripsi |
|
| Profil ergonomi lengkap macOS, iPadOS, dan iOS |
|
| Panduan hierarki material Liquid Glass (OS 26 / macOS Tahoe) |
|
| Kumpulan pedoman Split View, Morphing Tab Bar, dan Trackpad iPadOS |
|
| Kumpulan pedoman Floating Tab Bar, Large Title, dan Safe Area iOS |
|
| Pedoman arsitektur desktop macOS (kompatibilitas v1) |
|
| Formula matematika koordinat |
π Struktur Direktori Proyek
apple-style-mcp/
βββ src/
β βββ index.ts # CLI entry point (stdio server)
β βββ server.ts # MCP SDK Server & JSON-RPC 2.0 dispatcher
β βββ registry.ts # ToolRegistry & ResourceRegistry
β βββ types.ts # Kontrak tipe protokol MCP
β βββ core/
β β βββ errors.ts # Hirarki custom domain error classes
β β βββ fs/safe-fs.ts # Pemindai direktori aman & path guard
β β βββ platform/ # Spesifikasi profil macOS, iPadOS, & iOS
β βββ server/
β β βββ logger.ts # Structured JSON logger + PII & path redaction
β β βββ shutdown.ts # Graceful shutdown (SIGTERM / request draining)
β βββ tokens/
β β βββ token-definitions.ts # Single source of truth design tokens
β β βββ renderers.ts # Renderer CSS, JSON, TypeScript, & SwiftUI
β βββ knowledge/
β β βββ hig-topics.ts # Basis pengetahuan 13 topik Apple HIG
β β βββ pattern-comparisons.ts # Matriks komparasi 6 pola UI lintas platform
β βββ audit/
β β βββ detector.ts # Detektor otomatis platform proyek target
β β βββ audit-engine.ts # Mesin evaluasi kepatuhan multi-platform
β βββ components/ # 21 template komponen produksi (macOS/iPadOS/iOS/Shared)
β βββ tools/ # Implementasi McpTool handlers
β βββ resources/ # Implementasi McpResource providers
β βββ __tests__/
β βββ server.test.ts # Suite pengujian unit & integrasi (Pola AAA)
βββ .github/
β βββ workflows/ci.yml # GitHub Actions CI Quality Gate
β βββ ISSUE_TEMPLATE/ # Template Bug Report & Feature Request
β βββ PULL_REQUEST_TEMPLATE.md # Template checklist Pull Request
βββ CHANGELOG.md # Catatan rilis SemVer
βββ CONTRIBUTING.md # Panduan kontribusi & standar Clean Code
βββ SECURITY.md # Kebijakan keamanan & fitur proteksi bawaan
βββ LICENSE # Lisensi MITπ§ͺ Testing & Quality Gates
Proyek ini dilengkapi pipeline verifikasi kualitas terpadu (npm run verify) yang mencakup pemeriksaan tipe statis, linting tanpa any, pemformatan kode, pengujian unit/integrasi dengan ambang batas coverage ketat, dan kompilasi produksi:
# Menjalankan seluruh gate verifikasi sekaligus
npm run verify
# Atau menjalankan masing-masing perintah:
npm run typecheck # tsc --noEmit (strict mode)
npm run lint # ESLint flat config (0 warnings, 0 explicit any)
npm run format:check # Prettier code style verification
npm run test:coverage # Vitest + v8 coverage (>92% line coverage)
npm run build # Build ESM + TypeScript declarations ke dist/π€ Kontribusi & Keamanan
Silakan baca CONTRIBUTING.md untuk standar penulisan kode (Clean Code, SOLID, batas 30 baris/fungsi, dan pola pengujian AAA).
Untuk kebijakan keamanan dan pelaporan kerentanan, lihat SECURITY.md.
π Lisensi
Didistribusikan di bawah MIT License. Lihat file LICENSE untuk informasi selengkapnya.
Dikembangkan oleh Ahmad Eko Kurniawan.
Available Tools
9 toolsaudit_apple_projectB
Mengaudit kepatuhan arsitektur, konfigurasi Tauri v2, safe-area mobile, ergonomi sentuh 44pt, dan styling Liquid Glass Apple HIG pada proyek macOS, iPadOS, dan iOS.
Inputs: platforms, project_path.
audit_desktop_projectC
[Alias Kompatibilitas] Mengaudit kepatuhan arsitektur, konfigurasi Tauri v2, dan styling desktop macOS native pada direktori proyek.
Inputs: platforms, project_path.
compare_platform_patternB
Membandingkan bagaimana suatu pola antarmuka Apple HIG (navigation, modality, context_actions, notifications, window_and_safe_area, typography_and_ergonomics) diimplementasikan di macOS, iPadOS, dan iOS.
Inputs: pattern (required).
get_apple_hig_ruleA
Melihat penjelasan teknis, formula matematika, dan pencegahan bug untuk aturan desain Apple HIG lintas macOS, iPadOS, dan iOS (termasuk Liquid Glass, Zero-Shift Geometry, Safe Area Insets, Split View, dan Floating Tab Bar).
Inputs: topic (required), platform.
get_design_tokensB
Menyediakan design tokens resmi Apple HIG untuk macOS, iPadOS, dan iOS (Liquid Glass & Classic Vibrancy, Apple System Colors & Brand Custom, SF Pro typography, safe-area insets, dan chrome geometry) dalam format CSS, JSON, TypeScript, atau SwiftUI.
Inputs: format, platform, design_era, palette_mode, +1 more.
scaffold_apple_app_templateB
Menghasilkan struktur starter dan file konfigurasi (tauri.conf.json, tokens.css, index.html safe-area) untuk proyek macOS, iPadOS, dan iOS dengan dukungan dry_run dan proteksi overwrite.
Inputs: app_name (required), identifier (required), dry_run, overwrite, +5 more.
scaffold_apple_componentB
Menghasilkan kode komponen React + TypeScript produksi bergaya Apple HIG untuk macOS, iPadOS, dan iOS (Traffic Lights, Zero-Shift Sidebar, Command Palette, iPad Split View, iOS Liquid Glass Tab Bar, Bottom Sheet, dll).
Inputs: component (required), platform.
scaffold_base_app_templateC
[Alias Kompatibilitas] Menghasilkan struktur starter atau menuliskan file konfigurasi (tauri.conf.json, tokens.css, AppShell starter) untuk proyek desktop/mobile baru.
Inputs: app_name (required), identifier (required), dry_run, overwrite, +5 more.
scaffold_macos_componentC
[Alias Kompatibilitas] Menghasilkan kode komponen React + TypeScript produksi bergaya Apple HIG macOS, iPadOS, dan iOS.
Inputs: component (required), platform.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 9 tools
The tool set suffers from significant redundancy due to aliases (e.g., audit_apple_project vs audit_desktop_project, scaffold_apple_component vs scaffold_macos_component). An agent might face confusion when presented with functionally identical tools, degrading the usability of the set.
The tools mostly adhere to the consistent verb_noun pattern, such as get_design_tokens and scaffold_apple_component. The presence of aliases and slight naming variations does not fundamentally break the pattern.
With 9 tools, the set is well-scoped and appropriately detailed for its highly specialized purpose of Apple HIG implementation and auditing.
The surface is robust, covering component generation, full application scaffolding, design tokens, and architectural auditing. The set covers nearly all necessary lifecycle stages for HIG implementation.
Related MCP Connectors
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Give your agent a real design system: tokens, measured WCAG contrast, and rules to follow.
Run accessibility, contrast, and design token audits and file QA issues from your AI coding tool.
Design systems your AI agent builds with and you reshape, plus standalone React components.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to extract design systems, analyze components, and maintain design-code consistency from Figma files, providing intelligent component analysis and accessibility compliance.103 npm27MIT
- AlicenseAqualityBmaintenanceProvides Apple Human Interface Guidelines design tokens (colors, typography, Liquid Glass constraints, SwiftUI mappings) as structured data for AI coding agents.445 PyPI37MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to generate bespoke design systems by synthesizing OKLCH color palettes, chamfer highlights and spring physics, teaching layout composition grammar, and returning micro-interaction primitives and component blueprints. Also audits JSX/TSX/HTML through a senior design director's lens to score and critique UI quality.1MIT
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to ground UI work in real product screens by returning concrete screen references, design references, and licensed fonts, icons, or animated icons on request. It also ships a bundled design workflow, command playbooks, and connection diagnostics that work without an API token.-