内容
# hig-mcp — 苹果HIG设计标记语言适用于AI编程代理
**一个MCP服务器，为Claude Code、Cursor和任何MCP客户端提供苹果人机交互指南的格式化数据** — 真实的系统颜色值、字体大小、Liquid Glass约束和SwiftUI映射 — 而不是容易误读的文本或过时的十六进制颜色码。
## 每个苹果开发者（及其代理）当前面临的问题
在WWDC25上，苹果公司不仅发布了Liquid Glass，还悄悄地**更新了系统颜色调色板**（HIG更新日志，2025年6月9日）。`systemBlue` 不再是 `#007AFF`，而是 `#0088FF`。
这意味着：
- **每个大型语言模型的训练数据都是错误的**。询问代理关于iOS颜色的问题，它会自信地使用2025年之前的调色板。
- **HIG是文本，不是数据**。苹果公司以网页的形式发布指南；代理获取一个网页需要花费大量标记，然后仍然需要猜测数值。
- **Liquid Glass有规则，但没有人将其写在单一的地方** — 模糊预算、复合层上限、对比度在模糊后测量、强制减少透明度回退。代理默认情况下会违反所有这些规则。
您最终会审查生成的SwiftUI代码，它看起来似乎是正确的，但实际上却在每个地方都略有偏差。
## hig-mcp如何解决这个问题
精选、验证的标记文件存放在**服务器内部** — 离线、确定性、几乎为零标记 — 文本从 [sosumi.ai](https://sosumi.ai) 即时获取，因此指导永远不会过时。询问 `color`，您会得到当前的WWDC25后规格表格，而不是2023年的记忆。
| 工具 | 返回内容 | 网络 |
|---|---|---|
| `hig_get_tokens` | 按类别设计的标记：颜色、字体排版、材料、布局、SwiftUI、SF Symbols | 否 |
| `hig_check_liquid_glass` | Liquid Glass防护 + 针对您上下文和平台的具体检查清单 | 否 |
| `hig_swiftui` | HIG组件 → 正确的SwiftUI API + 应应用的标记 | 否 |
| `hig_fetch` | 当前HIG页面为干净的Markdown（通过sosumi.ai） | 是 |
## 工作原理
通过stdio（Python、FastMCP）提供的四个工具。格式化部分是您拥有并可以扩展的纯JSON（`src/hig_mcp/data/`）；文本部分委托给sosumi.ai的DocC-to-Markdown渲染，而不是重建。每个值都带有出处标签：
- `apple-system` / `apple-hig` — 苹果公司发布的事实（系统颜色、字体大小、44pt点击目标）。
- `wcag-aa` — 4.5:1对比度规则。
- `figma-effect` / `community-bestpractice` — 有用的数值，苹果公司没有发布，但已标记，您可以确认。
- `verify: true` — beta版本API名称会更改；请通过`hig_fetch`或Xcode确认后再发布。
诚实的数据胜过自信的数据。
## 快速入门
```sh
pipx install hig-mcp
claude mcp add hig -- hig-mcp
```
任何MCP客户端，配置表单：
```json
{ "mcpServers": { "hig": { "command": "hig-mcp" } } }
```
`hig_fetch` 默认目标为 `https://sosumi.ai`；可使用 `HIG_SOSUMI_BASE` 重写。
## 内置调用计数器
每次工具调用都会在 `$XDG_STATE_HOME/hig-mcp/calls.jsonl` 中追加一行JSONL — 时间戳、工具、调用客户端（来自MCP握手中的 `clientInfo`）；可使用 `HIG_MCP_CALL_LOG` 重写。这样您就可以知道哪些代理实际使用了它：
```sh
jq -r .client ~/.local/state/hig-mcp/calls.jsonl | sort | uniq -c
```
## 常见问题
**为什么不直接获取developer.apple.com？** 文本会消耗标记，并且仍然不包含机器可用的值。这里的标记是即时、离线和当前的。
**它是否取代sosumi.ai / apple-docs-mcp？** 不 — 它故意将文本委托给它们，而只拥有它们不提供的格式化层。
**哪些平台？** 目前为iOS / iPadOS，包含验证的macOS字体大小；值跟踪当前HIG（最后一次验证于2026年7月，WWDC26后）。
## 法律
Apple、苹果人机交互指南、SF Symbols、SwiftUI和Liquid Glass是苹果公司的商标。本项目与苹果公司无关，也未得到苹果公司的认可。没有重新分发HIG文本 — `hig_fetch` 在运行时检索页面，捆绑的数据文件包含带有原始注释的实际设计值。MIT许可证仅涵盖此存储库的代码和数据文件。
*关键词：苹果HIG MCP服务器 · 人机交互指南 · 设计标记 · Liquid Glass · SwiftUI · iOS 26 · macOS Tahoe · 模型上下文协议 · Claude Code · Cursor · AI编程代理*
MCP 市场