# apple-design-mcp

Live [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) as a CLI and MCP server.

Apple’s HIG site is JavaScript-rendered, so agents cannot read it directly. This package fetches Apple’s DocC JSON and renders it as Markdown — Getting started, Foundations, Patterns, Components, Inputs, and Technologies — for iOS, iPadOS, macOS, tvOS, visionOS, and watchOS.

It does not vendor Apple’s text. Pages are fetched live and cached on disk.

## Requirements

- [Node.js 20+](https://nodejs.org/)
- git
- macOS, Linux, or Windows

## Clone and install the CLI

```bash
git clone https://github.com/rncrosby/apple-design-mcp.git
cd apple-design-mcp
npm install
```

`npm install` also builds `dist/` (`prepare` runs `tsc`).

Put the CLI on your PATH (pick one):

```bash
# This machine only, from the clone
npm link

# Or install the clone globally
npm install -g .
```

That exposes three names for the same binary: `hig`, `apple-design`, and `apple-design-mcp`.

Check it:

```bash
hig --help
hig toc
hig get color
hig search "touch targets"
```

Without linking, run it from the clone:

```bash
node dist/cli.js toc
npm start          # starts the MCP server on stdio
```

Optional: cache every HIG page so search is local and fast:

```bash
hig sync
```

Cache location: `~/Library/Caches/apple-design-mcp` on macOS, `$XDG_CACHE_HOME/apple-design-mcp` or `~/.cache/apple-design-mcp` on Linux. Override with `APPLE_DESIGN_CACHE`.

---

## Add the MCP server

The server speaks **stdio**. After `npm install` in the clone, the entrypoint is `dist/cli.js mcp`.

In every snippet below, replace `/ABS/PATH/apple-design-mcp` with the absolute path to your clone (for example `/Users/you/Developer/apple-design-mcp`).

If you already ran `npm link` / `npm install -g .`, you can use the global binary instead:

```json
{ "command": "hig", "args": ["mcp"] }
```

```toml
command = "hig"
args = ["mcp"]
```

Restart the client after editing config.

### Cursor

**This repo:** already includes [`.cursor/mcp.json`](.cursor/mcp.json). Open the clone in Cursor, run `npm install`, then **Cursor Settings → MCP** and enable `apple-design`.

**Any project / globally:** create or edit `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (all projects):

```json
{
  "mcpServers": {
    "apple-design": {
      "command": "node",
      "args": ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
    }
  }
}
```

Cursor UI: **Settings → Cursor Settings → MCP → Add new global MCP server**, then paste the same JSON.

Grok models inside Cursor use this same Cursor MCP config. You do not add a separate Grok entry in Cursor.

### Claude (Claude Code)

From the clone:

```bash
claude mcp add --transport stdio apple-design -- node dist/cli.js mcp
```

From a global install:

```bash
claude mcp add --transport stdio apple-design -- hig mcp
```

Or commit [`.mcp.json`](.mcp.json) (already in this repo) so Claude Code picks it up for this project. Approve the server when Claude Code prompts.

**Claude Desktop** — edit:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "apple-design": {
      "command": "node",
      "args": ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
    }
  }
}
```

Quit and reopen Claude Desktop.

### Codex

CLI:

```bash
codex mcp add apple-design -- node /ABS/PATH/apple-design-mcp/dist/cli.js mcp
```

Or edit `~/.codex/config.toml` (global) or [`.codex/config.toml`](.codex/config.toml) in a project (this repo already has one):

```toml
[mcp_servers.apple-design]
command = "node"
args = ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
```

Codex CLI, the IDE extension, and the Codex desktop app share `~/.codex/config.toml`. In a session, run `/mcp` to confirm `apple-design` is connected.

### Grok (Grok CLI / Grok bot)

Grok reads `~/.grok/config.toml` globally, and [`.grok/config.toml`](.grok/config.toml) in a project (this repo already has one).

```toml
[mcp_servers.apple-design]
command = "node"
args = ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
startup_timeout_sec = 30
```

If the Grok CLI supports it:

```bash
grok mcp add apple-design -- node /ABS/PATH/apple-design-mcp/dist/cli.js mcp
```

Grok also loads Claude Code’s `.mcp.json` / `~/.claude.json` when present, so configuring Claude Code in this clone is enough for Grok in the same directory.

---

## What agents get

| Tool | Purpose |
| --- | --- |
| `hig_search` | Search the HIG (`query`, optional `platform`, `limit`) |
| `hig_get` | Fetch one page as Markdown (slug, title, path, or Apple URL) |
| `hig_toc` | Full table of contents |
| `hig_list` | List topics, optionally in a section (`Foundations`, `Components`, …) |

Resources: `hig://toc`, `hig://{slug}` (for example `hig://color`). Prompt: `hig_review`.

Typical flow: `hig_search` → `hig_get` the best slug → cite the Apple URL.

The first full-text search that misses on titles downloads every HIG page into the local cache (or run `hig sync` once). After that, search is local and fast.

## CLI

```bash
hig toc
hig list Foundations
hig get color
hig get buttons --json
hig search "touch targets" --platform ios
hig sync
hig cache
hig mcp
```

## Library

```ts
import { HigClient } from "apple-design-mcp";

const hig = new HigClient();
const hits = await hig.search("Liquid Glass");
const page = await hig.get("materials");
console.log(page.markdown);
```

## Develop

```bash
npm install
npm test
npm run build
```

## License

MIT for this software. Human Interface Guidelines content is © Apple Inc. Canonical source: [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines/). This project is not affiliated with Apple.